Documentation in Agile: How Much and When to Write It?

| by Ben Linders Follow 14 Followers on Jan 23, 2014. Estimated reading time: 3 minutes |

A note to our readers: You asked so we have developed a set of features that allow you to reduce the noise: you can get email and web notifications for topics you are interested in. Learn more about our new features.

The Manifesto for Agile Software Development values "working software over comprehensive documentation". This core value asks us to think about how much and which kinds of documents are needed and when they need to be written.

In the blog post Minimum Viable Deliverable Jonathan Berger writes about communicating design decisions. He shared his view on using documentation:

The Agile Manifesto prefers “Working software over comprehensive documentation”, so why are designers spending time on artifacts the user will never see? Agile seeks to minimize waste, so taken to its logical extreme, all documentation is waste. That doesn’t mean documentation can (or should) be done away with entirely; it’s necessary for teams to function (particularly at scale). But it does suggest that minimizing documentation is a Good Thing, and that designers ought to be seeking to communicate design decisions with the least amount of work possible.

Jonathan provides suggestions how you can minimize documentation:

1) socialize the idea that “less artifact can be better” among your team

2) always ask the question: what’s the least amount of deliverable that we need right now?

Ashish Sharma wrote about balancing documentation and discussion in Agile essential, valuable, timely documentation:

The goal in Agile should be to find the right balance between documentation and discussion. Documentation is an important part of every system, Agile or otherwise, but comprehensive documentation as such does not ensure project success. In fact, it increases your chance of failure.

He mentioned three criteria that you can use when deciding how much documentation should be written and when to write it:

Essential: Document with just barely good enough detail.

Valuable: Document only when we actually need it, not when we want it.

Timely: Documentation should be done in a just-in-time (JIT) manner, when we need it.

Michael Nygard described a process view to documentation. He suggests to begin with the end in mind:

I often find processes with no consumers. Pure waste! Literally nobody uses the output, but the producer doesn't realize it.

Processes, including their inputs and outputs, could be described from the perspective of the consumer as Michael suggested. He shared a set of questions that you can use to do this:

  1. Who is the consumer?
  2. What do they need?
  3. How do you deliver it to them?
  4. How do you know when they're ready for it?
  5. How do you produce it?
  6. What inputs do you need to produce it?

Tom de Lancey started a discussion early 2013 on LinkedIn about Emergent Documentation: One way that agile is very different from waterfall:

Many people are very uncomfortable letting go of the familiar documentation that they are used to: Systems Requirements, Systems Design, Vision and Scope, use cases, schemas, work-flow diagrams, Rational Unified Process artifacts, etc. Many cannot reconcile boiling all that documentation into a five sentence story.

He described an approach on documentation which he called “Emergent Documentation”:

(…) we do not want to waste time and effort in documenting something that we have not yet discovered how to do. We document as we discover. We document only what we actually DID, as opposed to what we thought we were going to do.

One of the benefits of this emergent documentation approach as described by Tom is that:

Documentation becomes part of the development process, not a separate activity. Since the documentation is actually useful, the whole team has an interest in maintaining it. Each story has a separate task to update the WIKI (a SharePoint web site that connects to each story).

Mario Moreira wrote a blog post about right-sizing documentation in an agile world. Right-sizing as Mario described is a response to the large amounts of documents that software projects had or have:

Right-sizing means that the level of effort applied to write and maintain the documentation plus the value of that written document should have a greater return on investment (ROI), then not having that information readily available (i.e., the effort it would take reconstruct the information and impact of not having that information for current decisions).

His blog post provides guidance on right-sizing documentation. Some of his suggestions are:

  • Documentation should take on a collaborative nature.  It should not be written by one person to perfection, and then shared with others.  It should instead be shared often during draft to gain input.
  • Focus on just barely good enough documentation and avoid big upfront details which typically means a lot of guessing and wasted time.   Barely good enough means document what you currently know.
  • Documentation can take many forms.  It is not only a Word document, documentation can live on a wiki, in the Agile planning tool, as comments in code, and much more

How do you do documentation in Agile? How much and when?

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

What about knowledge sharing for visual learners by Doug Smith

I am generalizing but after working with software engineers for over 25 years, I believe most would prefer to forgo documentation. My issue is this. In a world of high-tech where technology changes so fast and for those that don't spend their time reading articles or previous worked in an area, many concepts are new. My company recently experienced a network outage that I believe had been documented with an architecture diagram showing processes, messages, etc., I know I would have started thinking about loads on the system, does my existing environment give me what I need, what happens if messages are lost,etc. I think too often we rely on verbal communication to exchange ideas and I for one am too embarrassed at times to say, "Stop, draw me a picture because I have no idea what you are talking about." or I would have concerns that people would start looking at me and say where the hell did he come from? Why don't you know that? Believe me, I've already had that sad to me in another form. Some of us went to school 30 years ago and may not have worked in this area. I know that after our stand-ups I start documenting all our decisions in our stories as comments because if I don't write it down, I am going to forget. Hell I can't remember what I had to eat two nights ok or even last night for dinner so why would you expect me to remember something you mentioned quickly in passing when I have no reference point, no screen to look at, or no page to look at in a design. Doing the best I can, but it is tough to work in an Agile environment

Re: What about knowledge sharing for visual learners by Jon Leer

I totally agree with you Doug. The doc minimalist works for developers but not for content use after the deployment. The details you mention and formerly were captured in the legacy dev docs at least left a footprint from which user docs, training, and marketing material could be built.

Everything today is "lien" and "just in time", but the understanding on how to fit the built product with the learning process of everybody else between development and ROI requires a lot more thinking than just leaving it to the last minute. Unfortunately what developers think you should "get it", turns out in a lot of cases to not be intuitive for the user.

Iteration for the nation by Martijn Oost

I am missing one aspect of agility here... Iteration and feedback! Just enough. Then get feedback on what is missing/unclear and improve. Very important that aspiring agilists realise that paradigm shift is core to agility. Software, stories, documentation, team everything in the feedback loop. Rinse and repeat. It's like the agile salvation ;-) Let go of needing to get it right in one go. It's a journey, not a destination.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

3 Discuss

Login to InfoQ to interact with what matters most to you.

Recover your password...


Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.


More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.


Stay up-to-date

Set up your notifications and don't miss out on content that matters to you