PM Articles > Kent McDonald > The Benefits and Costs of Documentation

The Benefits and Costs of Documentation

by Kent McDonald

I have been working in a project environment for over 15 years, first as an application engineer and program manager for an automotive parts manufacturer, then as a business analyst, project manager, or program manager in a variety of information technology projects. What is the common denominator in all these projects? Documentation. My role on most of those projects could easily appear to be all about producing documentation. On top of that, I love writing, one of the reasons I write this column. So you would think I would be a huge advocate for producing documents on projects.

I am not.

Don't get me wrong, project documentation has benefits, when done correctly. Project documentation also has costs which are often exacerbated by the amount of documentation teams choose to produce, the way in which they produce it, and the way they use it. At its core, project documentation exists to aid communication and to serve as institutional memory. Many project teams run into problems when they start believing that documentation is intended to be the main form of communication, the primary storehouse of knowledge about the project, and a means of tracking progress in the project.

Piling these different expectations on project documentation leads teams to produce more documents than they really need, produce them in inefficient ways, and place way more importance on their completion that is warranted. When teams keep the proper perspective about documentation, they tend to experience many more of the benefits and fewer of the costs involved with project documentation. I would describe the proper perspective as that expressed by Ron Jeffries several years ago on an agile discussion group:

There are two types of documentation:
  1. Documentation requested by stakeholders
  2. Documentation the team needs to be effective

Let's take a closer look at both of these types of documentation and some appropriate ways to handle each one of them.

Documentation Requested by Stakeholders

The documentation that your stakeholders explicitly request is part of the solution that the team is trying to deliver. This kind of documentation includes user guides, support documentation, and operating instructions, among others. A good way for handling this type of document is to treat them as if they were a feature. When a stakeholder requests a particular document those requests get sequenced along with everything else so that stakeholders can decide whether new functionality is more important to them than the documentation. If you find that the documentation is important, determine why they are asking for it and what they hope to accomplish with it. Watching the stakeholders do their work can be a good way to understand why the documentation might be needed.

Armed with that knowledge you can craft the document specifically to meet that purpose. Don't try to use design documentation, which was intended for conveying a design, as a way to convey information to those trying to maintain the system. The design documentation may not accurately reflect the system's final state. Plus, that document was structured to convey design information, not to provide a quick guide to how the system was actually built.

When you know what documents are needed and their purpose, determine the best time to create those documents. In some cases, it makes sense to work on the document as you build the system (help documentation, for example). In other cases it makes sense to create the documentation after the system is built. Either way, write the document specifically for the intended purpose.

It also is usually a good idea to craft these documents at a system level, rather than a project level. Most of the consumers of the documentation do not care which project implemented a certain set of features in a product or system, they care more about the system as a whole. Since they are looking for information in this context, producing documents with this same perspective instantly makes it more useful. If information about a system is split into multiple documents depending on which project implemented the system, users may never know where to look to find the documentation they need. The other benefit of this approach is that you don’t have to create a new document for every project that touches a system; you can just make the relevant updates to existing system documentation.

Documentation the Team Needs to be Effective

The other type of document is those things that the team needs to do their job effectively. The vast majority of the documents project teams create fit into this category, but if you really take the wording to heart (those things the team NEEDS to do their job effectively) many of those documents actually go away. When the team relies more on face-to-face discussions on an as needed basis, they find that the documents now primarily aid communication and serve as institutional memory.

These documents no longer act as the sole means of communication, or as the only vehicle by which knowledge is transferred from one person on the team to the other. Looking at what they have to do, the team finds that they have been creating many of their documents because it was what they have always done, or because it was mandated by their process. Once the team identifies which documents they actually find helpful, they can focus on creating those, and using them in helpful ways, and abandon the documents that don't add any value.

So the benefits of documentation come into play when it satisfies a need that a stakeholder has or it helps the team become more effective. Documents add cost when they are not requested by a stakeholder, or if they get in the way of the team effectively meeting their objectives.

Not all comments are posted. Posted comments are subject to editing for clarity and length.

Thanks for this perspective. What was not listed is documents required by legislation.
Often PM forget contractual and legal documents, thus fail to give holistic guidance.

After nearly 40 years in the IT game, my opinion on end-user documentation is the best approach is to get end users to write it. As part of the contract, the customer agrees to provide an (intelligent !) resource to work with the team, write all the end-user docs, and arrange for its review and approval.

Otherwise the customer is usually unhappy with the quantity, quality and cost of docs produced by the team. They want more, they want it better and they don't want to pay another penny! This approach makes it their problem, not the team's problem.

My second piece of advice is to improve the quality of information passed on to future maintenance staff by NOT documenting it. Instead, get a camera, and sit the developers in front of it, then get them to talk about what they did, why they did it, what seemed like a goof idea at the time, and any particular info they think maintainers ought to be aware of.

Yes, it may be amateurish, but it's quick and easy to do. You can cover off a lot more than can be covered in writing, and you'll find the guys say the stuff they'd never dare write down.

The comments to this entry are closed.

©Copyright 2000-2017 Emprend, Inc. All Rights Reserved.
About us   Site Map   View current sponsorship opportunities (PDF)
Contact us for more information or e-mail
Terms of Service and Privacy Policy

Stay Connected
Get our latest content delivered to your inbox, every other week. New case studies, articles, templates, online courses, and more. Check out our Newsletter Archive for past issues. Sign Up Now

Got a Question?
Drop us an email or call us toll free:
7am-5pm Pacific
Monday - Friday
We'd love to talk to you.

Learn more about ProjectConnections and who writes our content. Want to learn more? Compare our membership levels.