Problem
I need to remember why we added or changed a requirement
Solution
Maintain a separate Change History table somewhere in the requirements specification document. The table should have a row for each released revisions / versions of the specification. Each row should have at least the following columns:
1. Date published
2. Version number
3. Author(s)
4. Change Description
The Change Description column should summarise the changes in each version. Your word processor or wiki engine should be able to provide detailed text change information; the Change Description should focus on providing a business overview of each significant change. It is an equivalent idea to using commit messages in source code repository systems like subversion or git; the repository system provides detailed line-by-line changes, but the commit message provides a short description of the purpose of the changes.
A well-formed change description item may include:
1. Label of affected requirements (preferred), or document section numbers.
2. Source or origination of change (e.g. meeting date, "email from JBloggs 24 May 2011")
3. Business justification of change.
Related tips:
- Once the specification has gone through several iterations, the Change History table can become quite large. Include the History of the current specification version only at the front of the document; archive the History of previous versions in an Appendix at the end of the document.
- Try not to duplicate requirement or supporting notes information in the main body of the document and in the Change History. If the business justification is too long for a simple summary in the Change History, include it as a dated Supporting Note alongside the affected requirements, leaving just a short summary in the Change History.
Example
| Version | Date | Author | Change Description |
|---|---|---|---|
| 0.2 | 4 May 2011 | R J Smith | Updates after 1st review: 1. Added Section 4 for initial design ideas 2. UI0030. Clarified that updates are realtime 3. P0015. Updated 1yr goal target <- JB statement 2nd May |
| 0.1 | 20 Apr 2011 | R J Smith | Initial version after 17th Apr brainstorm session |
Discussion
A requirement specification, as a collection of requirement statements with a given scope, is subject to change throughout its life, well beyond version 1.0 of the application(s) it describes. When new team members join the project, perhaps replacing existing staff, the context and decision making behind the choice of historical design solutions is often lost. This can make ongoing maintenance of the system more complex, as the answers to questions such as “Why was this done like that?” or “Is it safe to change that behaviour” may require such contextual knowledge of the project’s own history.