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:

  • A Wiki that contains the steps required to set up the application and a list of config files and config options can be considered essencial documentation – especially for developers who join the project at a later time. Also I would strongly recommend documenting the basic architecture (for example the different layers like database, storage backend, front-end application and JavaScript user-interface – how do they communicate with each other?).
  • 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 outdateduseless 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

Agile Manifesto