How Much Documentation Is Enough?
Tips every developer needs for creating documentation that doesn't impede your software development cycle.
by Brian Noyes

Posted August 13, 2002

Documentation is a key artifact of the software development process. It comes in a range of formats, and provides persistent process information at major development stages. Software process documentation has its pros and cons, but it's never a good idea to have none.

Documentation captures important project information at major points in the development lifecycle. It helps developers convey progress and follow-through to customers or managers, and it's a handy reference for future projects that might require similar steps. It can help new personnel get up to speed on a project, its development timeline, and the best way to apply their skills. Depending on its details and metrics, it might be a reference for future proposals and bids.

Documentation does have pitfalls, however. It is often time consuming, costly, and does not directly contribute to an end product. It might be difficult, leading to decreased morale for a developer stuck with too many documentation tasks. It's also difficult to keep documentation synchronized with rapidly evolving software development production cycles.

To offset these drawbacks, companies need to answer some questions before beginning production: how much documentation, in what form, with what types of content, at what depth, for what audience? These are hard questions, and the answers will differ for every project. The amount of documentation needed will vary with different customer requirements, management goals, developers' skills and the software methodology. Successful answers must not overburden developers or the project budget, and must help prevent losing information.

Developers usually cringe at the mention of documentation. They don't like to do it. I think programmers innately believe that cutting code is fun, and writing documents is troublesome. I believe this will change, however, as the tools for documentation evolve, and the conceptual distance between documentation and code decreases through the use of modeling and automated documentation tools. Then documentation will become simpler and more enjoyableeven for a programmer.

Documentation usually follows the phases of the software development lifecycle: Requirements, Design, Implementation, Test, and Deployment. The amount of documentation dedicated to each phase depends on customer and management desires. A whiteboard discussion might be enough if you are employing an extremely agile methodology, but heavyweight processes that require peer review and management approval will require more.

Different parts of your process may require different levels of formality. For example, government contracts often have rigid guidelines for the documentation of each phase, particularly Requirements and Test. Government contracts might also require customer approval for completion and acceptance. Whether you need to provide insight into the design will depend on the contracting model.

An internal Web development project or a commercial shrink-wrapped utility product might require less documentation. In these cases, it is the project manager's responsibility to select the appropriate level based on the complexity of the task, the skills of the programmers, and the process model.

Traditional forms of documentation include requirements, design, and plain-text test documents that contain a few graphics and block-and-flow diagrams. These are often authored manually, so they can be merged into a final document. If traditional documentation is required for your projects, it is best to create templates so all the documents will conform regardless of who might be generating them. This also ensures that items are uniformly placed as they are authored. Go to Software-Engineer.org for a site that provides several free templates in exchange for your registration at the site.

Modeling is a key focus area for software documentation. There are many model types, but the most prevalent is the Unified Modeling Language (UML). Using UML, you create model diagrams and elements that capture information for requirements, design, implementation, test, and deployment. You can forward-engineer (automatically generate code) or reverse-engineer elements from your code by using high-end UML tools. This method helps sync your documentation with all implementation and design issues that arise throughout the development of the software system. The model and the information it contains become your documentation. In addition, UML tools provide options to export and print model information into linear forms for print or online publishing.

Many agile methods endorse modeling as a standard for documentation, but others say models are unnecessary and too heavyweight for documentation. Go to the Agile Modeling Web Site for an example that links agile methods to modeling. Many tools exist for creating UML models you can choose, depending on your budget and code integration requirements. Go to Objectsbydesign.com for a site that provides links to most tools.

So, how much documentation is enough? As much as you can produce while meeting project requirements, staying on budget and schedule, keeping developers on-track and securing information. There isn't a boilerplate approach to software documentation. But do some advance planning, use the tips I've outlined, and you'll compile useful guidelines for documentation while staying within the deadlines of a rapid software production cycle.

About the Author
Brian Noyes is a consultant, trainer, and writer with IDesign Inc. Brian specializes in architecture, design, and coding of .NET distributed data-driven Windows and Web applications, as well as office automation and desktop productivity applications. He's an MCSD with more than 12 years of programming, design, and engineering experience, and is a contributing editor for asp.netPRO and other publications. E-mail him at .