1 March 2012

Agile Documentation

Last Thursday I pointed you at Scott Ambler's Agile Modelling website.

One of the pages there referred to Agile Documentation.  Coincidentally, earlier that day I bumped into an old essay by James Shore on The Art of Agile Documentation.  Also coincidentally I was burdened with reading a terrible quality project document the Friday before and am teetering on the brink of creating one myself.  (Peer pressure is a terrible thing.)

So this Agile Thursday I thought I would share some links to posts on the topic, starting with James and Scott.

  • The Art of Agile Documentation by James Shore
    • James describes the three types of documentation; 
      1. Work in progress docs, 
      2. Product docs and  
      3. Hand-off docs
  • The Documentation Myth, again by James
    • This time James flips the typical defensive stance of "Documents are good but conversations are better" and "Good agile teams produce great documentation" by focusing instead on why documents are produced (to provide accessible answers to questions.)
  • Agile/Lean Documentation by Scott Ambler
    • Scott writes quite a comprehensive essay discussing the purpose and meaning of documents, motivations and techniques for keeping them lightweight, who should be creating them, the use f templates and the introduction of cruft into documents.  It's well worth the read.
  • The Requirements as Inventory Metaphor by Business Analyst blogger Jon Babcock
    • JB briefly and concisely discusses the concept of requirements as inventory.  I can't write too much to describe it or my description will be longer than his.  The topic is an important one to understand and underlies several of the motivations to improve requirements documentation and modelling practices.
  • Agile Documentation by Scott Selhorst 
    • Scott discusses the idea of iterating documents just like you might iterate your code.  Addressed in Scott Ambler's essay, this is an essay exclusively on the topic.

These four sources are a pretty good starter pack that you should be able to digest in an evening.  As usual I would really like to hear your feedback or to hear of any other good sources on this topic.  Please add your comments.


  1. Hi! Just a quick note to let you know that your blog has proven to be of great value to what I am working on right now. Thanks!

  2. Glad to be useful :)