When should we create a document on an agile team?

When transitioning to an agile mindset people invariably ask about how documentation is addressed on agile teams.  Some documents, such as system overview documentation or operations manuals, are still a valuable part of the overall solution being delivered by the agile team.  More often than not a document, such as a logical data model (LDM) or detailed requirements model, isn’t needed at all because it can be replaced with a more effective strategy or the document can be greatly simplified compared with what a traditional team would develop.  This of course is a shock to most traditionalists, particularly for those who currently spend most of their time creating such documents.

To help people understand the agile approach to documentation creation, we find that it’s valuable to describe the logic that disciplined agilists follow.  This logic is captured in the following flow chart.
Agile documentation logic
Let’s walk through the decision points one at a time:

  1. Do you need a document?  There is a significant difference between needing a document, perhaps to persist important information, and wanting a document.  If you’re creating the document to communicate information to someone else then you really need to question its creation.  Research into media richness communication has found that detailed documentation is the least effective strategy available to you – better options include overview documentation, video conferencing, and of course face-to-face (F2F) discussion. For a second example, many organizations still follow a traditional, documentation-based approach to IT governance and as a result many teams are forced to create documents solely because someone in a governance roles wants it to be created (or at least the team perceives that they want it).  Sometimes people want a document because they fear that the information it would contain would be lost, not realizing that the older documentation becomes the less it is trusted (see Documentation CRUFT), so in effect the information is effectively lost even when it is captured as written documentation.  The point is that many documents aren’t really needed, they are merely wanted – if the latter, isn’t it better to deal with the real people and help people to recognize they don’t really need the document after all?
  2. Is there a better option?  In many cases there are significantly better alternatives to writing documentation.  For example, instead of creating a detailed written requirement specification when you follow an acceptance test-driven development (ATDD), also known as a behavior driven development (BDD) approach, you capture requirements in the form of executable specifications.  Granted, this takes a different set of skills and tools to perform, but in the long run it offers far greater value to your team than written specifications.
  3. Will you maintain the document? If you’re not willing to maintain a document throughout what should be its useful lifespan then don’t create it.  If this isn’t an option, then at minimum only work on it until the point where you’re still able to viably keep it up to date.  Documents that aren’t maintained aren’t trusted, and therefore not used.
  4. Do you understand what the consumer of the document actually needs?  The only way that you’ll be able to create an effective document is if you know what the audience for that document actually needs, and the best way to do that is to work with them closely.  Your goal is to create a document that is just barely good enough (JBGE), or just sufficient, that fulfills their needs and no more.  For example, instead of creating a detailed architecture model using a software-based modelling tool, co-located agile teams will often prefer to create whiteboard sketches which they leave on their workroom walls.  Yes, a pretty architecture model would be nice to have.  But the whiteboard sketch gets the job done, it is much easier to evolve, and much less expensive to create.

When an organization transforms to agile many traditional IT professionals will struggle at first with taking an agile approach to documentation.  In traditional software development, and in particular traditional IT governance, documentation is used as a crutch and worse yet a band-aid over organizational dysfunction.  We can no longer afford this and must instead be smarter about our approach to whether and how we write documentation.

For more information about agile approaches to documentation, we suggest you read the article Agile/Lean Documentation: Strategies for Agile Software Development.

Have any Question or Comment?

7 comments on “When should we create a document on an agile team?

Valentin Tudor Mocanu

In many cases I found co-existence of two wrong and “opposite” cases:
– document what is not necessary or make documentations to detailed
– do not document what it is essential
and that is a fundamental WASTE and misunderstanding .

Practical experience prove me that:
– essentials are very useful and can be managed easier
– details are only sometime useful and difficult to manage

“Document essentials” could be an Agile practice:
– in most of the cases we will need some documents, and in almost all these cases essential are necessary
– “Document essentials” offer a good support for “System metaphor” practice that have a lot of benefits

Example of benefit: it is very unlikely that a team member or a system user to understand the overview of a system or of a component only by assembling the details. That could take to much, could be inaccurate or could be never accomplished.

“Document essentials” work very good with other Agile practices:
– Envisioning (requirements and architecture) from Agile Modeling/Disciplined Agile (AM/DA)
– System Metaphor from XP
– Just Barely Good Enough from AM/DA
– Document Late from AM/DA
and fits well with the YAGNY (You aren’t gonna need it) … it is very likely You ARE gonna needed it!


A corresponding concept is TAGRI – They ain’t gonna read it. See http://www.agilemodeling.com/essays/tagri.htm for details.

Keith Collyer

Follow up to my last comment. David Parnas and Paul Clements wrote about this over thirty years ago, before “Agile” even existed, in their brilliant paper “A Rational Design Process: How and Why to Fake It”.

Keith Collyer

That’s interesting, my last comment appeared, but not the one before it. Trying again.
This whole idea of face-to-face communication being “best” is a castle built on sand. It relies on the (itself contentious) idea of Media Richness Theory, which only applies to communication with a high degree of equivocality. Equivocality is a horrible word used presumably because the authors wanted to use a word that was less well understood (oh the irony) than ambiguity. A well-written document has little ambiguity and moreover is easy to challenge where it is ambiguous.
And let’s not forget, face-to-face is the preferred medium for shysters, where you get steamrollered into agreeing with something that, on reflection, is sheer nonsense. Which would have been obvious if it were written down and you had time to think.
If you need a permanent record (and if you are building anything other than the most trivial system you do), then you have little choice but to use a document. I might have understood something in a F2F meeting, but that was six months ago, and without a record of that meeting (i.e a document), I have forgotten the details. And the person I had the meeting with has now left to go to a competitor, so I can’t meet again.
Now that’s not to say you need a massive document covering everything. There is nothing to stop you from building the documentation in an agile way, just like the software. In fact, given that the code itself is just the documentation of what the compiler is supposed to do, why do people think it is any different?


Keith, interesting thoughts. In http://disciplinedagiledelivery.com/wp/choose-the-best-communication-technique-available/ we discuss the need to persist information and as a result indicate that documentation is one of many options to do so.

You may also be interested to know that I’ve written a fair bit about agile documentation strategies over the years, starting with my initial work in Agile Modeling.

Keith Collyer

Hi Scott, I see in the post you mention that you reference Media Richness Theory. I’ve looked into that and I find it sadly lacking in any real justification except, as I mentioned earlier, where there is a lot of ambiguity in communication. Another basic problem with MRT is that it assumes that having a rich communication channel is beneficial. Counter-intuitively, perhaps, this isn’t necessarily so. MRT proponents often use the example of body language to support the case, but that fails to take into account that body language is highly personal and cultural, dependant on things outside of the context of the communication, and subject to massive misinterpretation. It also totally ignores the fact that a rich communication channel implies a high receive bandwidth, but that isn’t necessarily the case in interpersonal communication. If I am paying attention to a person’s body language, am I really listening to their words? On the other hand, with a document, I can take my time to ensure I understand it correctly, and can ask questions to clarify without so much risk of the other person being offended.

Scott Ambler

Keith, yes, cultural issues are very important factors in the effectiveness of communication. A head nod has very different meanings across cultures for example. As does the word “Yes” for that matter (a completely different issue).

The thing with body language is that a lot of it is subliminal. But as you point out, if you’re purposefully focusing on it then you’re taking cognitive processing away from listening (or watching for other things).


Leave a Reply

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