Software engineering is a much younger discipline than are other branches of engineering. We see this in the continuing evolution of attitudes and approaches to requirements. In early days, there were no requirements. In later days, there were volumes of approved textual statements. Eventually, there were formal models. Today, sometimes models and statements are merely interim deliverables because code becomes the requirements.
In the spirit of this evolution, we present a requirements framework and methodology that may be different from what you are doing. Its three prominent characteristics are a framework, a new model, and visualization. The framework ensures completeness of all requirements. The new model is the Decision Model, transforming important business thinking into a tangible and manageable business requirement. The visualization simulates user scenarios, alleviating the need for abstract specifications or models.
Based on experience, this approach accelerates the productivity and success of a software engineering project. It begins with a framework.
The Framework
Our approach adopts the Zachman Framework for Enterprise Architecture(1), which is the foundation for all modern Enterprise Architecture theory. Thus, it will likely fit into most – if not all – architectures. The Zachman Framework proposes a decomposition of complex systems, processes, or organizations. As a quick review, it consists of six columns representing the dimensions which are the interrogatories (What, How, Where, Who, When, Why). It consists of six rows representing the views of target audiences (Planner, Owner (the “business”), Designer, Builder, Sub-contractor, and Functioning Enterprise). Therefore, there are 36 cells. Each contains content unique to the cell, which ought not to appear in any other cell. So, it is a normalized schema of decomposition artifacts because it disallows unnecessary duplication of content among cells. Zachman calls the cell content primitives. Primitives connect to all primitives in the same row.
Using this framework for requirements ensures completeness. Mostly, each cell represents an appropriate model. Each model corresponds to a particular audience view. Each model connects to other models, along with appropriate metadata.
To keep it simple, we explain the framework and methodology in six simple steps.
Step 1: Validate the completeness of the Project Charter.Step 2: Confirm the appropriate requirements deliverables within the framework.Step 3: Prepare a visualization of the target scope.Step 4: Employ the right models.Step 5: Include the new Decision Model.Step 6: Repackage and Present a Holistic Requirements Deliverable.
Step 1: Validate the Completeness of the Project Charter
Many people overlook this step, but it is a most vital activity.
To get started, begin in Row 1 in Error! Reference source not found., the perspective of the “Planner” of the system, which consists simply of six lists. Using the project charter as your scope, create the lists referenced in row 1:
- List of things (information)
- List of business processes
- List of locations
- List of organizations
- List of events/cycles
- List of business goals or strategies, and business decisions (more on this later).
If the project charter is unclear about any of these lists, request sponsors to fill in the gaps before proceeding.
Step 2: Confirm the Appropriate Requirements Deliverables within the Framework
Use the framework to identify the kinds of requirements deliverables appropriate for the project. This means moving onto Row 2 because it represents the business audience. For each cell, describe the corresponding deliverable to the level of detail as prescribed by Zachman. (It is a principle of the framework that there is no difference between the detail in the cells from top to bottom, but rather a difference of perspective only. In other words it is as important for business requirements to be as detailed as the technical design is, but for different audiences.)
Many deliverables should be models, each one aimed at a different dimension of the Framework. Error! Reference source not found. contains a list of useful deliverables for business requirements.
Figure 1: Useful Deliverables for Business Requirements
 |
Step 3: Prepare a Visualization of the Target Scope
Visualization is the simulation of important user scenarios of the system. It enables exhaustive examination of business requirements. Consider completing the visualization before modeling because it reveals requirements arising from these interactions. Visualization takes place in three distinct phases, as illustrated in Figure 2. A product for this is iRise(2).
The first phase is Scenario Ideation. Divide the requirements into a set of scenarios generally grouped around a set of logical functions. Explore each set of scenarios through steps all scenarios are complete. In some cases, users may decide that there is no value to creating a high-fidelity simulation, and that an analysis level simulation is sufficient.
During the Scenario Ideation and the Analysis-Level Simulation, participants identify a large number of requirements. A wider group of participants discovers more when given access to the simulations. This leads to more exhaustive discovery of requirements that may not have been identified using conventional methods. It also leads to higher levels of adoption of the product.
The High-Fidelity Simulation delivers a refined deliverable. In the tool, maintain the requirements traced to features displayed by the simulation. Use the simulation as one of the major inputs to the models created in the subsequent steps.
During all these phases, which are iterative in nature, detailed notes are maintained tracing these as requirements to the elements within the visualization. These notes will be used in framing the textual requirements in the last step.
Figure 2: High Level Phases of Visualization (source: iRise)
 |
Step 4: Employ the Right Models.
When possible, favor models to represent business requirements over textual statements of functional requirements. Accompany each model with descriptive text.
“Models provide graphical and semantic representations of their target aspects in ways that are easier to view and understand than are textual statements or narratives. Because each model captures just one aspect of the system, several models, each orthogonal to the other, provide a sufficiently complete view of the proposed system(3). Therefore, models provide shared understanding and for assistance in developing related textual requirement statements. In some approaches, a model serves as input for the automatic generation of the system. This is called Model Driven Architecture (MDA).
There are at least three reasons for modeling each dimension with its own model. First, each model reduces complexity. Second, each model enables independent change of its dimension from other dimensions. Third, it turns out that a model specifically tailored to the characteristics of the modeled dimension best represents each dimension. For example, data is best modeled in diagrams that show the relationship of each data entity to another, where icons represent the data entities and lines represent data relationships. On the other hand, process flow is best modeled in diagrams that represent flow of process tasks, where icons represent the process tasks and lines represent process sequence.” (von Halle and Goldberg, 2010)
Step 5: Include the New Decision Model
There are at least two compelling reasons to include the Decision Model as a new requirements deliverable. The first one relates to how business rules are the forgotten dimension in most requirements. Ken Orr states in the preface to our book, “Indeed, business rules are perhaps the most important, unresolved problem facing business and IT. A great many organizations are not so much the masters of their business rules but prisoners of them.” That is because the business rules in those systems represent is the one dimension we have omitted from requirements, but that we now recognize as something we need to manage much better. We are unable to do so because we have not had a separate deliverable for them.
The good news is that the Decision Model fills this gap as a stand-alone model just for organizing business rules similar to how the Relational Model is for data. In a Decision Model, business rules are in their atomic form, governed by 16 principles, including three forms of normalization.
The inherent structure of business logic in the Decision Model is similar to the inherent structure that Dr. Codd detected in data almost 40 years ago. This is a very exciting development for requirements practitioners. Further, the Decision Model shares metadata with, and has connection points to, the other models commonly used in requirements today.
A second, even more compelling reason to include the Decision Model is its potential impact on the business itself. Practice proves that when business leaders can view their business logic in a tangible, rigorous Decision Model structure, it becomes a magnet for better business decision-making. This has a profound effect not only on requirements, but also on organizational maturity and business performance.
It should come as no surprise that most systems, processes, and organizations are driven by decisions defined by logic. Until now, we did not know how to find them. In our requirements approach, we start looking for them in Step 1 above, creating a list of them. We deliver models for them in Step 4. Figure 3 depicts the connections of Decision Models to other deliverables.
Figure 3: The Decision Model and Connections to Other Deliverables
 |
Step 6: Repackage and Present a Holistic Requirements Deliverable.
Upon completion of the visualization and models, organize the requirements document according to the framework, packaged with the high-fidelity visualization. In this stage textual requirement (“Shall…” or “Ability to…”) may be prepared from the notes accumulated and maintained during the visualizations and model preparation. This is not an afterthought: rather it is a recognition that textual requirements are driven by the visualization and modeling activities rather than the other way round. Finally, deliver a presentation of the requirements, imbedding a video (“protocast”) of the visualization, highlighting the key features of the system. This will prove an invaluable in-briefing document to the project.
Summary
There is a need to improve the quality of requirements gathered in projects developing software systems for business because a large proportion of projects fall short or fail due to inaccurate or missing requirements.
The requirements approach in this article combines common practices with visualization and the Decision Model. The most important parts of this approach are:
- Select a requirements framework that represents complex systems or organizations as discrete dimensions.
- Use the framework to identify the requirements deliverables for your business audience.
- Adopt a visualization methodology to elicit requirements before completing models.
- Deliver models for each dimension of your project.
- Include the Decision Model for important business thinking behind business decisions.
- Organize the requirements document according to the framework, packaged with the High-Fidelity Visualization. Prepare, if required, a set of textual narrative to the requirements. Complete the requirements with a presentation of the highlights, including a protocast of the visualization.
1. Also referred to as the Zachman Framework, which is a Copyright work of John A. Zachman of Zachman International. Details can be found in Chapter 13 of The Decision Model (Goldberg & von Halle, Auerbach 2010).
2. iRise is the registered trademark of iRise.
3. The operative word is “sufficiently”; after all, if we created an exhaustively complete and comprehensive model of every aspect of the system, it would no longer be a model, but the system itself! Rather like Lewis Carroll’s map in “Sylvie and Bruno Concluded”, where the mapmaker’s “grandest” solution to absolute accuracy in their map of the country was to make it on a scale of a mile to the mile. Unfortunately, it could never be spread out without blotting out the sunlight, and the population had to resort to using the actual country as their map, discovering that it did nearly as well!
