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 clamp down early in the life of a project by setting standards for version control and ensuring that these standards are used. If everyone knows what is expected early on, a lot of time, effort, and patience will be saved. But it isn't necessary to develop a complex style manual. Simple controls can be very effective and cheap to implement: For example, use a file-naming convention that includes the document version number and make sure version numbers are increased every time a document is changed.
If the project uses a configuration management tool such as Microsoft’s Visual SourceSafe or Computer Associate's Endevor to control versions of code, consider trying to use it to control document versions as well.
A side benefit of keeping old versions of documents is that they provide a valuable history of the project, especially projects lasting a year or more.
Don't Make the Process Too Onerous
Document control shouldn’t be made too difficult. Apply a reasonable standard. Technical staff may resent anything they view as bureaucracy and will appreciate timesaving processes. Don't forget that the aim is to cut development costs, not increase them. Reasonable controls, like increasing version numbers and having a central repository, are easy to keep up if established at the beginning of a project; setting up a new system halfway into a project is unpopular and difficult.
Think about Audit and Quality Requirements
In large companies, audit and quality departments must be satisfied with the documentation. Handing over a consistent set of documents gives the appearance of a well-run project, whatever else may be going on!
Think about Peripheral Departments
This is a subject close to my heart, since I work in Information Security, an area that receives papers from many different projects. Documents frequently arrive out of the blue with a requirement for comments within two or three working days. A core document list, accompanied by the project plan, allows me to schedule my time. Good scheduling helps me reply in the allotted time with a properly considered response, not a quick judgment after a rushed read-through. If a peripheral department doesn't have time to read a document properly, problems may show up at later stages in the process, when they cost more to fix.
Include Documents in the Change Management Process
All projects need a change management process for controlling the impact of changing business requirements. In the e-world, project teams must deal with constantly changing business requirements. A typical change management process consists of evaluating the impact of a change by determining what needs to be changed, how long it will take, how much it will cost, and how it will effect the rest of the project. When these answers are known, the proposed change is accepted or rejected. If accepted, the change is introduced into the project in a controlled way. When evaluating the impact of a change, remember to identify any amendments needed to the documents on the core list. Then ensure that the documents are updated appropriately, increasing version numbers as needed.
Conclusion
At present I can’t give any figures for how much good documentation saves or bad documentation costs. My views stem from experience, not specific research. I'm hoping to get some qualitative data on the value that good documentation can provide to software development projects as part of my study for an M.A. in technical authorship. In the meantime, I try to follow my own advice wherever I can and persuade others to do likewise.
