BackgroundGathering 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.
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.
FormatYou will notice in the downloadable example that each requirement takes on the templated form of:
ExplanationWhat 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.