x Take the InfoQ Survey !

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

by Ben Linders on Jan 23, 2014 |

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?

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

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

1 Discuss
General Feedback
Marketing and all content copyright © 2006-2015 C4Media Inc. hosted at Contegix, the best ISP we've ever worked with.
Privacy policy