Documenting Software Architectural Requirements

Download Example

Background

Gathering requirements for a software project can definitely be challenging. Maintenance projects for familiar products are usually easier than starting a project for a new product. After searching through many books, articles, and gaining some practical experience, I have thus far developed a direct and simple method of documenting architectural requirements.

Note: Hands down the best article I have read is written by Peter Eeles at IBM. His article can be found at http://www.ibm.com/developerworks/rational/library/4706.html#iratings. Ultimately Eeles' process is a quality attributes type of approach to gathering requirements (see some of the links below).

• http://en.wikipedia.org/wiki/Non-functional_requirement
• http://www.softwarearchitectures.com/go/Discipline/DesigningArchitecture/QualityAttributes/tabid/64/Default.aspx
• http://www.softwaretestinghelp.com/what-are-the-quality-attributes/

Whether or not you use Eeles' approach for gathering requirements, I believe this method for documentation is fairly flexible and natural; especially for those using quality attributes.

Format

You will notice in the downloadable example that each requirement takes on the templated form of:

1. Statement:
     a. Question [optional]:
     b. Answer [optional]:
     c. Quality Attributes:
     d. Architectural Realization:
     e. Goal Metrics [optional]:

Explanation

What exactly is this the formatted structure about? Let's go over each line.

Statement: The statement is intended to be just that, a statement. Generally when discussions occur about what the application should or shouldn't do, statements by various stakeholders are made. Those statements should then be documented, hence the rest of the format is derived from the statement. Of course, all statements should be reviewed, revised, and approved by all key stakeholders. It is then up to the software architect to make sure that all statements will make sense technically.

Questions & Answers: Although these are optional, they may be helpful to facilitate clarification or future discussion. It should be noted that we may not necessarily be limited to one question and one answer. Feel free to add as many as necessary.

Quality Attributes: Which set of quality attributes we use and why we use them is beyond the discussion of this article (I used Eeles' in my example download).

Architectural Realization: As you will notice in the example document, architectural realizations are references to architectural design decisions shown later on in the document.

Goal Metrics: Depending on your company's policies regarding development requirements and post mortem analysis, we may need to document measurable goal metrics to further make design decisions and to ultimately measure the success of the project.

Justification

Why do I suggest this kind of format for documenting requirements? Well hopefully the straight forward statements will not scare off non-technical stakeholders while still providing a technical bridge from those statements to developers. Furthermore, when the "Why did we do that?" kind of questions arise, a direct correlation from architectural and code decisions can be traced back to their respective requirement statements. Finally, it is the intent that documenting a formal statement (hopefully approved statement), lends itself to reduce ad hoc scope creep. Or at least if scope creep does happen, we can at least show in post mortem the number of changes after initial development began.

MVC vs 3-Tier Pattern

I have had several people ask me what the difference is between MVC (Model View Controller) and Three-Tier architectural patterns. It is my intent to clarify the confusion by comparing the two patterns side-by-side. At least in part, I believe the source of some of the confusion is that they both have three distinct layers or nodes in their respective diagrams.

Three-Tier	MVC

If you look carefully at each diagram you'll notice the associations (arrow connectors) between the boxes are set up a little differently.

Three-Tier

A 3-tiered system really is made up of layers (think of cake layers). The UI Layer has access to the Business Logic Layer, and the Business Layer has access to the Data Layer. But the UI Layer cannot directly access the Data Layer. In order for the UI Layer to access data, it must go through the Business Logic Layer via some kind of interface. If it helps, you could think of each layer as one big loosely coupled component with strict design rules of access between layers.

MVC (Model View Controller)

In contrast, the MVC pattern obviously does not keep a layered system. The Contoller accesses the Model (a runtime data repository) and the View. The View then accesses the Model. Exactly how does that work? The Controller ultimately is the logical decision point. What sort of logic? Typically, the Controller will retrieve, build, or modify a Model base on some triggered action. The Controller then decides which View is appropriate via some internal logic. At that point the Controller will push the Model to View.

Note: Because I mostly develop with .NET, Microsoft has adopted the MVC pattern for ASP.NET with their own platform (see http://www.asp.net/mvc). You can certainly use the MVC pattern without Microsoft's platform, but why reinvent the wheel? I have been very happy using it so far.

When Do I Choose Which Pattern?

First of all, these two patterns are definitely not mutually exclusive. In fact in my experience they are quite harmonious. Often I use a multi-tiered architecture, such as a three-tiered architecture, for the overall architectural structure. Then, within the UI Layer, I use MVC. Something like the diagram below.