How to maintain up to date documenation about the current state of functionality in Agile environment

Question

Agile is suppose to be light on documentation. In the agile world it is highly likely that the original requirement changes very quickly based end user input or the changes in design. The new requirement gets captured in form of new user story which again could be very short lived and may change in near future. In this scenario it gets difficult to manage/maintain documentation about the standardized behavior for any functionality so that it could be refer back to for any future references. In IT world people sometimes tend to move quickly and it gets challenging to figure out how something was designed 1 year back and why. If there is any information experts would like to share on this, it would be great. Thank you

Answer 1

It depends on what you need. There is no predefined rules. Agile promote light documentation for requirements. It is however recommended to document the slice of software you build (user story) according your specific needs.

That's why I like the concept of the 'definition of done'.

In your definition you can specify that you need well written technical documentation about the functionnality you build, including why you choose that and that...

It's up to you.

The power of agile is that you can reduce waste a lot.

Answer 2

Build the user documentation into the software: an intuitive user interface in the software. Good software is self-explanatory. If needed, put additional documentation in the help system (tooltips, help-menu, etc).

On the technical side, keep the documentation in self-explanatory code and code-docs, express functionality in executable tests (from unit tests to acceptance tests). Put surplus information in a wiki that can be easily updated. Automate building building/publishing of the documentation-site, and follow the DRY principle: One thing should be documented only once, and referenced from there on.

Key points:

• Document well what needs to be documented (think typical user).
• Do not document the obvious.
• Good software is self-explanatory.
• Do not repeat yourself.
• Generate documentation from source code automatically.
• Keep specs in the shape of executable tests.
• Throw away stale docs fast.