Quality Time

How Good Documentation Cuts Development Costs

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.

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.

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.