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.