Agile Documentation, what is it?

Elroy Serrao asked a question leading to a good discussion about documentation on LinkedIn's Agile Alliance group.

His statement:

The whole "document via index cards" idea felt a bit weird though. Partly because I haven't been able to really view physical "index cards" as something that can be tracked, searched etc over a long period of time. So I was wondering if anyone would be willing to share their experiences, best practices etc. in this area.

The following is a couple of the high notes:

From Siddharta Govindaraj:

Think about how much value a piece of documentation produces. If you think it is worth it, then go ahead. If you feel it is overhead then dump it.
You need to ask yourself three questions: Who is the documentation for? What is it for? How will it be used?

From Levent Gurses:

There is no way in the world that I, or anyone else on my team, will spend time digging a cabinet of index cards to find out about the details of a story that happened 3-4 months ago. It will just not happen.

Instead we use a modern WIKI, like Confluence - which among other things keeps page versions. Requirements and stories captured in Confluence are always current and traceable. Combined with SCM labels and release notes, any person on the team is always 100% sure what's in Production, what's in Testing and what's currently being developed.

From Kevin Schlabach (me):

I'm most aligned with Levent's answer, but here's my simplistic cut at it-

If you do TDD... add a database & architecture model to your tests and you have your tech documentation (as much as is worth keeping up to date).

If you use automated Acceptance Tests... add a domain model and you have your business documentation.

If you use an electronic system for backlog management... you have your project documentation.

If you pair program and rotate pairs daily, you insure knowledge is spread throughout the team.

If you layer on a wiki, you can capture conversations for the few days it's needed until working software is built.

If you don't do some of these things, you might require more documentation to cover you when you want to ramp up new people or explain your API's to other groups.

This is a simplistic overview, but what I'm getting at is that you still need some documentation that goes beyond your index cards, but it can be a living, breathing part of your process.

Read up on some of Alistair Cockburn's work (Crystal). By applying game theory, you always think about working today to insure success (wins) tomorrow. Documentation is meant to be a way to survive in the future when needed.

From Gary Tinnes:

I have a rule: “the amount of a document that is read is inversely proportional to its size”. If you document, keep it short with lots of white space to make it look smaller than it really is. Focus on bullet points (clarification if needed) and graphics.