Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

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

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

Leia em Português

This item in japanese


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


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.

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

Community comments

  • What about knowledge sharing for visual learners

    by Doug Smith,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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.

  • What about lines of code not being clear enough? What about Javadoc, Doxygen etc.?

    by Sohrab Saran,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Documentation is essential for code to be easily maintainable. It is not feasible to come up with long and descriptive enough file, folder, variable, function and class names in code, such that there is no need for documentation at all.
    Imagine code without even a single line of comment. Even if word documents are there for requirements and design, people will generally have a tough time identifying what a particular function or line of code of interest, maps to in the requirements or design documents. To put things in proper perspective, imagine that you were to look at your own code after 10 years! Or imagine that all the developers of a particular codebase have moved on from the project, and now the project has to be maintained by a brand new team of developers who never got any code walkthrough.

    Now imagine code where the requirements and design are precisely documented as comments in the code. The comments follow Javadoc or Doxygen conventions so that during any phase of the project (especially the initial phases), we can auto-generate documentation from code, even if some/all the functions are 'skeleton functions'. I think that the original posts do not touch upon this approach, which is probably the best approach.

    Tools-wise, a better collaboration between developers and Business Analysts writing the documentation in the form of the initial user stories, might be needed. Specifically, BAs should know the version control system and be willing and able to create and edit documentation in source code files. The generated documentation can always be in a format like word or pdf format, for any analysis/reviews that need to be conducted abstracted out from actual lines of code.

  • Minimal documentation - What about traceability for regulatory projects?

    by andrew pienaar,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    When you work on a regulatory change you need to have bidirectional traceability ie: From the regulatory text to each individual test step within the test evidence.

    If you don't have fully traceable documentation and your organisation is in Pharmaceuticals or Financial services. The regulators can stop your organisation from operating and your top executives could land up in prison. I am working on a financial services regulatory programme that has that level of severity.

  • Re: Minimal documentation - What about traceability for regulatory projects

    by Ben Linders,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Thanks for elaborating on documentation in regulatory project.

    Given that bidirectional documentation is required, then it becomes part of the product and hence has value for the stakeholders.

    Has your company adopted agile? If so, have you seen any changes regarding the way documentation is created?

    Ben Linders

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

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