Telling Stories: A Short Path to Writing Better Software Requirements

Chapter 8. Reviewing, Reusing, and Maintenance

This chapter describes the process of reviewing and maintaining the entire document after it is complete and also discusses some possibilities for harvesting the content in later stages of development to create functional specifications and test plans, and for basic project management.

Review Cycles

As you work, process by process, section by section, you should share your work with key team members for feedback. Once the entire document is done, distribute review copies to the entire team and allow them enough time to provide feedback. Your work is not complete until it has been thoroughly reviewed.

I also recommend testing the document on a select group outside the project team, if possible, before circulating it more broadly.

It is impossible to produce polished work without external review. There will always be embarrassing typos, wrong assumptions, incorrect details, and many other corrections that are not apparent to you, the author.

Reviewing documentation can be tedious work, and most people don't like to do it. When reviewers are not responsive, you should assess the strength of the story elements in the document. Reviewers are more motivated when the executive summary is forceful and makes clear recommendations, and all of the data flow diagrams have compelling introductions that tie each section to the overall story. Also consider making your diagrams more comprehensible by grouping related processes and annotating.

If you are ...