Reviewing, Reusing, and Maintenance
This chapter describes some of the follow-on tasks after the document is completed. The author notes that the project description is a living document - it is never completed and done with so long as the systems are in operation.
Review Cycles
After the document is drafted, it will generally go through a formal review process - in fact, several of them, by different groups of stakeholders, each of which will provide corrections and amendments.
The author recommends informal review - send the document to the appropriate individuals to review at their leisure and meet with them individually if the response is not meaningful or timely.
The worst possible approach is to get everyone in a room and read the document to them. That may seem expedient, but such meetings tend to turn into free-for-alls and are not productive. The only time you should attempt to gather a group is when there is conflicting feedback - and then, gather only those who are in conflict.
Sign Off
Most organizations have a formal acceptance process - a sign-off in which parties formally indicate they have reviewed the document and it meets with their approval. Ideally, this should mean the document is finalized and there will be no additional edits, though in practice, they tend to trickle in, and need to be managed to prevent the project from meandering off-course.
After sign-off, the document may still be edited, but when changes occur, they should be documented (as all involved expect the sign-off version to be "final"). The author's recommendation is to make changes to the document itself (rather than having multiple versions) and to document these changes in a separate appendix (rather than attempting to do it inline) called a "change log" or "version history"
Even though changes may occur, a copy of the document should be archived at sign-off as a reference. Should problems arise and the system fail to meet expectations, this copy is used to determine where the blame lies (if the developers failed to deliver a solution that met requirements, requirements were not provided for expected performance, or a problem arose that made it impossible).
Having a pristine version of the sign-off documentation is particularly important when dealing with vendors (in fact, the document is part of the legal contract), but also important for political ones (when something goes wrong and people inside a company look to shift blame and avoid responsibility).
What Happens Next
After sign-off, the document becomes a blueprint and reference work used by the developers who are creating the software. The exact list of uses differ according to the project and the organization, but typically include ...
- Project Proposals - The project document is included in formal proposals to obtain budget. In most instances, the executive summary is included in the corpus of the proposal, with a reference to the full document.
- Functional Specification - Documentation is developed by the engineers for their own use. This is a much more technical document that includes detailed information about systems and applications, often to the granularity of code-level details.
- Project/Resource Management - The project proposal is used to develop plans for conducting the work, which means allocating people and funds to the project and managing the development task. This may also include capital budgeting (to acquire systems) and HR management (to train or hire skills needed)
- Test Plans - As part of development or a separate task, the system will be tested to determine if it performs the functions and meets the specifications as described in the project document.
Fundamentally, the project documents are the "bible" to which anyone will refer when they need information about the project or the system it describes.
Managing Requirements through the Project Life Cycle
Project documentation is a useful resource for the project manager, as a touchstone to determine whether the project is meeting the documented requirements. The author mentions a few books on the subject, written for project managers.
During the production process, the project may evolve and issues may arise that require revision to the product requirements.
Maintaining Requirements After the Application Is in Production
Even after the project is completed and the application is in production, there will be ongoing modifications and changes to the system. Ideally, the project documents should be merged into the systems documentation, which should be maintained as an ongoing record.