The Use of Documentation

Documentation! It’s what we do.

People approaching Agile software development for the first time often ask about what documents are required.  When I ask developers what annoys them most about other peoples’ code, I frequently get the answer that it’s not documented well.  And I can’t tell you how many times I’ve heard people express the opinion that Agile software development is undisciplined because you “don’t do any documentation.”

Why is documentation so important to us?

It’s because we’re used to using documents to carry our thoughts and ideas to other people, other places, other times.  Documents are good at the “other places, other times” part.  Documents can be good at transporting ideas to “other people,” but it’s really hard work.

Communicating via a document (Portions of this image courtesy of Briar Press we use a document for idea transport, we have to convert our thoughts into words in a way that the reader will convert back to thoughts very similar to our own.  Even the best writers are unable to do this reliably for all readers.  Most of us write just clearly enough that we can understand our own writing, and we’ve got the help of knowing what the original thoughts were.

To write for another reader, we need to be aware of alternate ways our words might be interpreted, and edit them to be less ambiguous.  We must also predict the questions that our readers may have, and make sure that we answer those questions in a clear and understandable fashion.  That’s a lot of up-front planning for a simple document.

Professional writers spend a lot of time doing such planning, evaluating, and rewriting.  They also involve editors (the professional testers of the publishing world) to look at the document from other points of view.  They’ll generally send the document to multiple readers for review, and incorporate the feedback into revisions of their document.

Few, if any, of us will go to such lengths for a document intended just to support a software development effort.  That’s why Agile software development processes recommend a conversation, instead.  With a conversation, you get real-time feedback from the recipient of the information.  They can tell us how they’re interpreting our words, and we can revise or elaborate to clear up the misconceptions.  They can ask the questions on their mind directly, instead of depending on us to anticipate them.

Using a document to supplement communications (Portions of this image courtesy of Briar Press“But there’s so much technical detail,” you may say.  “What if we forget some important things?”

Yes, documents are good for helping us to remember things in the future. So write down anything you think will be handy.  Use that document to support your conversation–not replace it. In fact, you may want to create that document together, as part of the conversation. This can be a great technique for aiding clear communication.

Alistair Cockburn has said that “a project’s rate of progress is linked to how long it takes information to get from one person’s mind to another’s.” Don’t delay or derail this process by depending on documents as the vehicle.

2 Replies to “The Use of Documentation”

  1. Great!

    In addition to the speed of knowledge transfer, the ability of the process to create new knowledge is critical in software development.


  2. Software development is knowledge management. Speed of software development is equal to speed of knowledge generation + knowledge assimilation + knowledge sharing as an expert-apprentice pair.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.