Creating effective management control instead of bureaucratic procedural "hoops" saves time and cuts development costs. But well-defined procedures are necessary to keep documentation in sync with the rest of the pieces of the project. In this article, Gill discusses specific documentation-process elements that will help improve the overall development lifecycle.
Barbara M. Block's recent article in Intercom ("Faster, Better, and Cheaper: The Software Development Life Cycle," February 2001) described the classic waterfall approach to software development and how documentation should be used to drive the process forward. The waterfall model, as Block describes it, involves six stages of development: concept, requirements, design, build or buy, test, and implement.
I agree completely with the approach described, but in practice I have yet to encounter a project that uses the waterfall model exactly, regardless of the good intentions of the project manager.
More than fifteen years of experience in software development have shown me that project phases always overlap to some extent. Indeed, in large projects, overlap is essential—for example, implementation planning must begin early during the design stage. Changes to business requirements during the life of the project are also inevitable, especially in the fast-moving e-world. Typically, design and even programming may be under way before requirements are documented and approved. In addition, requirements inevitably change to some degree between the start of a project and final implementation.
This overlap between project phases, coupled with the need for a rigorous process to control changes to requirements, makes the role of documentation in a project even more important than that described in Block's article. Strong management control over documentation can help keep the project on track and reduce time-wasting confusion. The larger the project, the more important the documentation becomes. Good documentation can cut the cost of software development; bad documentation will add to the cost of a project, jeopardize delivery dates, and hinder everyone’s attempts to deliver "faster, better, and cheaper."
Delivering Good Documentation
Define the Core Document List
At the outset of a project, the project manager should define the core list of documents to be produced. This list will usually include a definition of the project requirements, a project plan setting out budgets and timetable, a testing plan, and an implementation plan. The list may be longer if the project is large (say, over 300 person days of effort or a period lasting more than six months) or if a set project methodology is being used.
Documents on the core list are important deliverables from the project and will be maintained—that is, kept up to date—throughout the project and possibly throughout the life of the system. Documents outside the core list can be called “working papers”: These documents should clearly show that they are one-off documents and will not be kept up to date. A simple way to do this is to include "Working Paper" as part of the document title and make sure everyone on the project knows and understands the convention. The project may require any number of working papers on specialized topics. These are produced as the need arises.
Set Up a Central Repository
All project documents must be held in a central repository to which everyone on the project has access. Documents held in one person’s PC are of no benefit to the project overall. On large projects, the team may need to nominate a documentation controller whose duties will include supervising the central repository, ensuring formal acceptance (signoff) of documents, and knowing who is working on any particular document at a given time.
Set Up Standards for Version Control
Strong version control of documents is essential. People waste a lot of time turning up at meetings with old copies or comparing dates on others' copies to see if they all have the same version. How frustrating to spend time commenting on a document only to learn that it’s out of date! Project managers must