Project Practitioners > Barely Sufficient Documentation

Barely Sufficient Documentation

By Kent McDonald

In a previous post I mentioned “yeah-buts” those objections people come up with when they are resistant of some sort of change.  One of the most common yeah-buts I run into when helping teams adopt agile is the idea of documentation. 

Some teams claim they are adopting agile, but are really just using that as an excuse to not do any documentation.  This leads to the popular misconception that agility = no documentation, which then becomes a common argument against adopting agile: “Yeah, but agile doesn’t do documentation, and we need documentation in our organization.” Never mind for a minute that statement contains another misconception – that all documentation is inherently good and necessary.

Whenever the topic of documentation in projects arises I like to bring up the idea of barely sufficient documentation.  I first saw this expressed in a Agile Project Management Yahoo Group posting by Ron Jeffries.  There are basically two kinds of documentation that a team should produce during a project:

  • Documents the team needs to do their work
  • Documents that the customer asks for

If there is a document that the team (notice I did not say process) needs, they determine what the document looks like, whether it makes sense to update it, and how long they should keep it.  Generally speaking these documents tend to have relatively short lives as they are used to help the team work through a problem or remind themselves of some key design decisions.

The other documents - those that are requested by the customer - are treated as requirements and should be prioritized along with all other requirements.  This means that the team has conversations such as: “We’d be happy to produce that 150 page specification for you.  We think that it’s probably 8 points.  What 8 point feature do you want us to defer so that we can create that spec?”

Documents required by “the process” are also treated in this manner, allowing the customer to indicate what value they derive from the documents that a process requires a team to produce allowing the team to only produce the truly important documents.

This philosophy about documentation is not just for agile approaches.  I encourage all project teams to take a critical look at the documentation they are being asked to do and determine whether they need it to do their work or if their customer is truly asking for it, and then to handle the documentation appropriately.

Related Templates
On agile projects, use your periodic retrospectives to ensure the documents you've created are still useful. In more formal environments, you may want to document your documents with something like this Deliverables Definition Form. Our Project Flexibility Matrix can provide a quick framework for deciding how important that really is, or weigh the pros and cons of paper vs CDs (and similar tradeoffs) with this tradeoff table format.

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

Timing of the documentation should be added here. Do the documentation that is needed at the time it is needed. No point documenting in details a required feature that might be pushed down the timeline and by the time you look at it again, the requirements are different because some process has changed in the business.
Other point: create documentation that can be re-used and that evolves along the project timeline, starting by being a high level requirement and ending up being a set of test cases and a documented system functionality. Don't create 5 different documents, it's a waste of time and money.

Agility is a state of mind, a way of living, not just a way of developing systems.

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

Follow Us!
Linked In Facebook Twitter RSS Feeds

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.