What to document in agile projects?
A posting in the Agile and Lean Software Development group on LinkedIn inspired me to think about the amount and type of documentation that should be created in agile projects. It is a misconception, if developers think that agile methods do not require any written documents. Here are a few (I think the most important) examples:
- Of course it makes sense to write down the core features to be implemented for each story, so that the developer knows what to do in detail. Otherwise, you can hardly estimate the scope of your tasks and/or you rely on the memory of a certain developer (you’re in trouble, if that person gets sick or leaves the project for other reasons). Many product owners think, it’s enough to describe the task with like 5 sentences. Wireframes and a list of possible user interactions are a good start and also help a lot during acceptance testing after the features were implemented.
- You should definitively document all implemented protocols for reference. Sequence diagrams are often useful for that. Even many standard protocols have optional features and 2 years later, no one will know what is implemented and what not. If you publish a public API, you have to document it in every case. APIs can often be documented half-automated using reflection and inline comments.
- What you should not document, is the code as such, because it changes a lot (refactoring) so that the documentation will be outdated, useless and even dangerous really quick. If you care about basic usability, the front-end should also not require any documentation. When was the last time, you read a user’s guide to use a Web site?
Working software over comprehensive documentation