Why Documentation Is Important in Agile, Too
I just read an article that questioned whether agile teams should relax the requirement that their user documentation be updated during each sprint. After all, the Agile Manifesto prefers working software over comprehensive documentation, so shouldn’t we be able to relax our requirement that documentation be updated in each sprint? Here’s the short version of my answer—absolutely not.
First of all, the Agile Manifesto is referring to internal documentation used by the team to guide the creation of the product, not external documentation that is delivered as part of the product. So, the first question to ask is: “Do we consider documentation to be (a needed) part of the product?” If the answer is yes, then the explicit conclusion is that the product is not shippable when the documentation is not ready.
The second question, then, is: "Do you relax the requirement that your product be shippable at the end of each sprint/iteration?" You can, but my recommendation is that you don’t. That’s a slippery slope. Instead, fix the underlying problem—your team is struggling to deliver documentation for every iteration.
Thinking outside the box, you can eliminate the need for documentation—by designing a user interface that is so self-explanatory, straightforward, intuitive, or perhaps guided and interactive that users do not require any documentation. Take into account the level of competence of your users and the learning curve that new users have to climb to reach that level of competence. This is almost definitely more work than creating documentation, but if done well, it results in a better product.
Your users don’t want to read a document—or use your software for that matter; they want to solve a problem. Anything that makes solving their problem easier, faster, and more enjoyable is a good thing.
Thinking inside the team-responsibility box, remember that agile encourages you to build teams of specializing generalists. Most software developers think of someone who can write UI code and backend database code (or whatever). However, you’ve already established that user documentation is part of the product—so it is fair game for the specializing/generalizing discussion.
If you have only one person on the team who can create user documentation, you have a risk. Just as if you have only one person who can create efficient, complex SQL queries or one person who can create elegant user interfaces. Cross-train your team. Pair up when writing documentation. Address the issue by making sure that you’re staffed to build everything you need to build—including documentation.
As a tweak that doesn’t directly solve the problem but makes it easier to deal with the problem and makes your product better, consider using goal-driven documentation. As you implement each use case or user story, write the documentation about how to do that specific thing. Don’t organize your docs around what the product can do—organize them around what your users can do.
