Best Practices for Agile/Lean Documentation


Ideally, an agile document is just barely good enough, or just barely sufficient, for the situation at hand. Documentation is an important part of agile software development projects, but unlike traditionalists who often see documentation as a risk reduction strategy, agilists typically see documentation as a strategy which increases overall project risk and therefore strive to be as efficient as possible when it comes to documentation. Agilists write documentation when that's the best way to achieve the relevant goals, but there often proves to be better ways to achieve those goals than writing static documentation. This article summarizes common "best practices" which agilists have adopted with respect to documentation.

Best practices for increasing the agility of documentation:

  1. Writing
    • Prefer executable specifications over static documents
    • Document stable concepts, not speculative ideas
    • Generate system documentation
  2. Simplification
    • Keep documentation just simple enough, but not too simple
    • Write the fewest documents with least overlap
    • Put the information in the most appropriate place
    • Display information publicly
  3. Determining What to Document
    • Document with a purpose
    • Focus on the needs of the actual customers(s) of the document
    • The customer determines sufficiency
  4. Determining When to Document
    • Iterate, iterate, iterate
    • Find better ways to communicate
    • Start with models you actually keep current
    • Update only when it hurts
  5. General
    • Treat documentation like a requirement
    • Require people to justify documentation requests
    • Recognize that you need some documentation
    • Get someone with writing experience

Author: Scott W. Ambler

Like this article:
  4 members liked this article


businessanalyst posted on Tuesday, May 20, 2008 7:17 AM
The article is really good and primes Agilists on documentation approaches. There is a lot of confusion on this area among early agile - adopters. I was one of them, but after reading this article, not only did I like it, but I have also shared it with my team and we are implementing a few of the best practices suggested. Thanks !
peeter posted on Wednesday, March 5, 2014 6:13 AM
IHi ella and keyilee,
t will definitely ease your work of handling a big project. As a project manager I use scrum in my projects. One of my friends referred me to use the Guide to Scrum Body of Knowledge by I like the concepts of sprints, daily standup meetings, etc. the SBOK Helped me alot in Understanding how Agile Project Management works.YAnd if u want to preapre for PMP ,U can prepare yourself for the PMP exam in one of the PMP trainingproviders like You can do minimal prep-work to get 40 PMI® Contact Hours and apply to PMI for PMP Exam before the class begins.
Only registered users may post comments.

Copyright 2006-2020 by Modern Analyst Media LLC