Agile Documentation

Agile values working software over comprehensive documentation – it is 1/4th of the original manifesto.  That doesn’t mean don’t document!  It means don’t document more than you need to document.  Documentation does have value, but the practice of documenting got excessive – that’s why a reaction to the bad stuff earned a spot as one of the pillars of agile.  How do you avoid over-reacting when changing a culture of over-documentation?

The Need for Documentation

We need documentation to help us communicate.  You can define an agile team as “the people creating the product.”  You can interpret “creating” as the people we normally think of as executing to accomplish the goals, or you can be more inclusive, and think of the people who have the goals as being part of the team too.

Philosophically, agile stresses collaboration.  Usually it is couched in terms of (1) people who are executing collaborate to devise the best solutions and (2) people who are part of the team collaborate with the people for whom they are creating the product.  Personally, my experience has been that projects with committed sponsors succeed, and projects without them fail – so I always think of the sponsors as part of the team.

Regardless of your definition – collaboration requires communication, and communication benefits from documentation.

Temporal Communication

Communication among groups of people happens over time.

Some collaboration is transient – communication happens right now, and is only important right now.  Other communications are persistent – the collaboration happens right now, but we need to remember later what we agreed upon and why.  There are variations of “right now” and varying degrees of “later”, but slightly oversimplifying,

  • There is communication for now.
  • There is communication for later.

Both are important.

Documentation, in the vision from your nightmares – giant requirements documents, architectural analyses, and detailed psychographic profiles – is very inefficient when communicating for now.

These massive documents, while getting in the way of a conversation, do provide the opportunity to remember (in the future) why we make the decisions we make (today).

Documentation, as emphasized in most agile discussions – user stories and acceptance criteria, on an index card, taped on the wall – is not a robust solution for communication that happens later.

This low-overhead approach to capturing today’s ideas actually facilitates and improves today’s conversation – but does not give us a record we can use in the future for why we made our decisions.

As an agile team, there are ways we can approach both the persistent and transient documentation tactics to make them more valuable.  We can tweak our transient documents to make them more useful for persistence.  We can take an agile approach to development of persistent documents, so that we only do just enough documentation – trading off the minimum amount of short term efficiency to avoid long-term blunders.

Transient Documents for the Future

The image above is from a workshop defining the product backlog for an initial sprint for a new project.  The team identified the most important stories for the first sprint, their acceptance criteria, and the size, in story points, for each story.  As part of scrum, the stories are written in user-story format, with acceptance criteria for each story identified and documented on additional index cards (taped to the index cards for the associated stories).  Great transient way to capture the must do and makes it better stories that the product owner is thinking about.

As a team, we made a couple minor tweaks to make these story cards more useful.  First, all of the stories were organized into themes that help establish the context (for the team), and combine the stories into “meaningful areas of focus” for communication with stakeholders.

Each story got a blob of color in the top left hand corner, identifying which of the five themes were being supported.  You can see a few of them circled in the image above.

We also developed a set of 8 proto-personas (prototype, early draft, very rough personas – almost stereotypes) that the overall product / project was designed to support.  Each persona got a different color star.

Each user story got a corresponding colored-star sticker to indicate for which persona the story has been written.  Specifically, when multiple personas could use a story, we identified for which persona we were implementing the story in this sprint.

In the “right now” world, these tweaks helped us understand, question, and confirm the themes and personas being supported in the first story.  Those conversations allowed us to reach pragmatic compromises about which stakeholders were going to benefit and when.  They also allowed us to craft the outbound message that is step one of stakeholder expectation management.

The list of themes changed while we were doing this – moving from 4 to 5 themes, as we realized that there was value in splitting one of the themes.  The group of proto-personas grew from an initial set of 3 to a set of 8, as we quickly realized that the team was trying to “build something for everyone” and we wanted to avoid the elastic user problem, and instead, roll out capabilities sequentially that satisfied valuable groups of users with similar goals and perspectives.

Culture Change for Stakeholders

As you would expect, having a bunch of cards stuck on the wall provides a great, visceral, now communication for the team – both in implementing and communicating.  However, cards on the wall is very transient.  It also doesn’t provide a good way to communicate with old-school stakeholders (imagine the execs who have their admins print out their emails for them to read and annotate – those folks still exist!).

This can make it hard for the “not part of the implementation” part of the team to collaborate and communicate.

In User Stories Applied, Mike Cohn stresses that the brevity of user stories is intentionally designed to facilitate (and I would add “dependent upon”) conversation.  I find it to be both a strength and a weakness of user stories.  It is strong because you can cover a lot of ground quickly (breadth) and capture a number of stories, much like the list above.  It is weak because the requirements documentation does not stand on its own – it requires conversation to fill in the details.  I’ve had some success using the “Verify that…” user acceptance tests as the method of documenting those details (depth), in conjunction with the brief, easily consumable stories.

Stakeholders in a Barrel

Those conversations happened as part of getting the stories defined, getting them on the board in the right order, and defining the acceptance criteria.  Stakeholders often have a short memory, especially when they were the ones making a compromise.  You need some way to retain the context of the conversation that led to the particular organization and content of the stories on the wall.

Persistent Documents in the Present

Agile proponents complain about the massive get-in-your-way documents that slow down the start of projects, prevent the teams from adapting to changing market conditions, and otherwise make it harder to deliver great products.  I agree.  Agile proponents also rail against the “build it all, then release it,” waterfall, process for creating software – and propose an alternative – iterative development of the software.  I agree again.

Why not apply the same principle of iterative development to persistent documents?

Consider the example above of using colored-star stickers to identify the people for whom each story is being implemented in any given sprint.  The majority of the time spent on this analysis is around understanding which people are important (to the success of the product), and for which people the ability to perform this user story is important (to the person).  The combination of these two importances is an input to prioritization.  A minimal amount of time is spent putting stickers on cards, and creating multiple cards for the same story (each with a different sticker for a different persona and potentially different acceptance criteria).

Add a tiny bit of overhead, and capture the information in a spreadsheet (or whatever).

The image above shows a mapping of use cases to actors.  It could just as easily show a mapping of user stories to personas.  The transition from thinking about actors to thinking about personas is a small one.  This chart comes from an earlier article on communicating a delivery schedule with use cases – it helps stakeholders get a big picture view of who benefits when – a user-centric, yet still top-down perspective.

Note: Another nuance to incremental delivery is that you can introduce the “bare bones” version of a story now, and the “better” version of it later.  You can also communicate that stories get better over time, for some users, with the same type of chart.

A very similar, and also simple to create table can show how each theme is getting “representation” within each sprint.  That view facilitates great discussions about trying to emphasize one theme and then another sequentially, versus doing the most important items in each theme first – gradually making progress in each theme.  Creating that view, and using it to communicate, has helped me address concerns that “external” stakeholders have shared about how a team appeared to be “chaotic and random” in their approach to prioritization and implementation.

Many Models

There are many types of documentation – and many types of models for emphasizing and discussing particular aspects of a complex system (like users and goals and solutions).  Creating a simple diagram like the following whiteboard sketch is almost required for effective transient communication in some projects.

[from Simple Agile Model Example]

When most folks are complaining about documentation, they are not complaining about the sketch above.  They would consider that sketch to be augmenting a conversation.  Fine.  That’s what I did, at the time.  Then I took a picture of it.  Suddenly, it was documentation.  A stakeholder came by later, confirmed that the system needed to work this way, and signed the whiteboard – and the photo was updated.

Every heavyweight document can start out this way.  And it can evolve.  It should evolve.  If you’re going to succeed, it must evolve as your team gets smarter, your competitors react, and your market changes.

The trick is that you don’t have to write the final version before you get started.  Capture at a high level what you know right now – just like a roadmap.  Capture in just enough detail what you need right now – just like a story backlog.  And change it as you go.


Documentation is not bad.  Documenting stuff you will never use is bad.  Documenting stuff you don’t need for a long time is risky, because it will probably change before you refer back to your document.

Documenting why you made decisions right now, as part of transient collaboration and communication is important, so that you collectively remember.  That documentation persists and your team can build upon knowledge, incrementally – just as your team builds upon the evolving code base, incrementally.


Post to Twitter Post to Facebook

This article was published on Tuesday, November 16th, 2010 at 3:15 pm and is filed under Agile, Business Analysis, Requirements, Requirements Models, Software development, User Stories.
You can leave a comment on this post

One Comment

  1. I used to do documentation reflections during the whole project thinking about the “ROI” of different documentation from past experience (does it really help, is it just effort, can it be automated, is something missing, can something put together to reduce redundancy and so on). It’s part of permanent process improvement here.

56 Trackbacks

  1. By marquinhosarm on November 16, 2010 at 9:21 pm

    RT @sehlhorst: Agile Documentation – transient & persistent new at Tyner Blain #agile #baot #prodmgmt

  2. By David Hobbs on November 16, 2010 at 9:45 pm

    Didn't include link in agile documentation tweet by @sehlhorst earlier — here it is:

  3. By Israel Santiago on November 16, 2010 at 10:13 pm

    By @sehlhorst: Agile Documentation

  4. By Kevin Brennan on November 17, 2010 at 12:14 am

    Reading: Agile Documentation #baot

  5. By Claudio B Kerber on November 17, 2010 at 12:28 am

    Muito legal esse post. Documentação ágil. RT @bakevin: Reading: Agile Documentation #baot

  6. By Bruno Arueira on November 17, 2010 at 12:29 am

    RT @oclaudiobr: Muito legal esse post. Documentação ágil. RT @bakevin: Reading: Agile Documentation #baot

  7. By Alltop Agile on November 17, 2010 at 1:33 am

    Tyner Blain – Scott Sehlhorst: Agile Documentation

  8. By Sara EM on November 17, 2010 at 6:34 am

    Agile Documentation #agile

  9. By Adrian Logan on November 17, 2010 at 8:37 am

    TynerBlain: #Agile Documentation

  10. By Fabiano Almeida on November 17, 2010 at 11:05 am

    A new interesting kind of thought about #Agile and documentation or "agile documentation"

  11. By DSN_XP on November 17, 2010 at 11:55 am

    RT @_sara_em: Agile Documentation #agile #DSN_XP thanks Sara (Again you are very very nice :o)

  12. By OneSpring on November 17, 2010 at 2:02 pm

    "Documentation is not bad. Documenting stuff you will never use is bad."

  13. By Rich Mironov on November 17, 2010 at 3:24 pm

    By @sehlhorst: Agile Documentation #prodmgmt #agile

  14. By Simon Witkiss on November 17, 2010 at 3:49 pm

    RT @sehlhorst: Agile Docs – transient & persistent > as well as remembering it helps link to overarching vision #in

  15. By Jeffrey Davidson on November 17, 2010 at 4:46 pm

    Reading: @sehlhorst Agile Documentation | Documentation is not bad, why do BA's fight understanding? #baot

  16. By VasilyKomarov_RSS on November 17, 2010 at 5:22 pm

    Agile Documentation

  17. By Juras Vetrau on November 17, 2010 at 5:31 pm

    Хороший принцип определения того, нужна ли подробная документация в проекте — "communication for now" / "for later" —

  18. By April Dunford on November 17, 2010 at 5:35 pm

    RT @sehlhorst: Agile Documentation #prodmgmt great post.

  19. By Vincent Roman on November 17, 2010 at 5:36 pm

    RT @aprildunford: RT @sehlhorst: Agile Documentation #prodmgmt great post.

  20. By Koven J. Smith on November 17, 2010 at 5:36 pm

    RT @aprildunford: RT @sehlhorst: Agile Documentation #prodmgmt great post.

  21. By selena on November 17, 2010 at 5:51 pm

    Agile Documentation: Iterate it, just like everything else | Tyner Blain: via @addthis

  22. By Koven J. Smith on November 17, 2010 at 6:38 pm

    Reading: Agile Documentation | Tyner Blain []

  23. By Alan Kleber on November 17, 2010 at 7:12 pm

    By @sehlhorst: Agile Documentation #agile

  24. By Christophe ORDANO on November 17, 2010 at 9:15 pm

    #agile Documentation : That doesn’t mean don’t document! It means don’t document more than you need to document –>

  25. By Mike Cottmeyer on November 17, 2010 at 9:31 pm

    Interesting Post… Agile Documentation

  26. By Mike Schmidt on November 17, 2010 at 9:33 pm

    RT @mcottmeyer: Interesting Post… Agile Documentation

  27. By Sandi Jones on November 18, 2010 at 3:09 am

    Yes. This. RT @aprildunford RT @sehlhorst: Agile Documentation #prodmgmt great post

  28. By Daniel Teng on November 18, 2010 at 4:37 am

    RT @mcottmeyer: Interesting Post… Agile Documentation

  29. By Phil Green on November 18, 2010 at 5:26 am

    Great post. RT @sehlhorst Agile Documentation – transient & persistent new at Tyner Blain #agile #baot #prodmgmt

  30. By Carol Kollm on November 18, 2010 at 4:51 pm

    RT @aprildunford: RT @sehlhorst: Agile Documentation #prodmgmt great post.

  31. By shivie on November 18, 2010 at 5:21 pm

    Agile Documentation

  32. By Rubén López on November 18, 2010 at 6:36 pm

    By @sehlhorst: Agile Documentation

  33. By Adam Bradley on November 18, 2010 at 7:01 pm

    RT @shivie: Agile Documentation

  34. By Hernan Garcia on November 18, 2010 at 8:02 pm

    Agile Documentation | Tyner Blain:

  35. By Ibrahim Saracoglu on November 18, 2010 at 8:24 pm

    Nice read… #Agile Documentation

  36. By Fabio Cevasco on November 18, 2010 at 9:36 pm

    Agile Documentation | Tyner Blain — — an interesting and comprehensive article on a hot subject (at least for me!)

  37. By Juanjo Falcon on November 18, 2010 at 10:02 pm

    RT @saracogl: Nice read… #Agile Documentation

  38. By José Antonio Estevan on November 18, 2010 at 11:08 pm

    RT @saracogl: Nice read… #Agile Documentation

  39. By Michael on November 19, 2010 at 8:02 am

    RT @sehlhorst: Agile Documentation – transient & persistent new at Tyner Blain #agile #baot #prodmgmt

  40. By Cristofer Weber on November 19, 2010 at 4:18 pm

    Agile Documentation

  41. By XP Injection on November 20, 2010 at 10:51 am

    Документация не есть зло. Бесполезная документация – это зло. Формальная документация – вот зло.

  42. By kevin berardinelli on November 20, 2010 at 8:52 pm

    the agile commercial development model and the issue of documentation

  43. By Ryutaro YOSHIBA on November 20, 2010 at 10:42 pm

    アジャイルにおけるドキュメントの位置づけについて詳細な説明 / Agile Documentation | Tyner Blain

  44. By Richard Laksana on November 21, 2010 at 6:12 pm

    Agile Documentation –

  45. By John Fraser on November 23, 2010 at 5:39 pm

    RT @sehlhorst: Agile Documentation

  46. By Ioan VÎNTOIU on November 27, 2010 at 7:40 pm

    Agile Documentation. I loved @sehlhorst ‘s blog post. (

  47. By João Cerdeira on November 28, 2010 at 5:57 pm

    By @sehlhorst: Agile Documentation

  48. By Alaeddin on December 8, 2010 at 8:19 pm

    “projects with committed sponsors succeed, and projects without them fail”

  49. By Antoine HULIN on December 20, 2010 at 1:04 pm

    Transient documentation and persistent documentation : #in #Documentation #Agile

  50. By Juanjo Falcon on February 10, 2011 at 2:04 pm

    Agile Documentation

Post a Comment

Your email is never published nor shared. Required fields are marked *


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>