The last session of the first day was about Agile Documentation. This wasn’t a session someone had prepared in advance. We discussed a bit about the topic. At first, there was a bit of confusion about what we were talking about. Part of the discussion was really about requirements. What information do you need to start the project or to determine the impact of new requirements upon the system. Another part was about what documents we need to write during and after the project.
What documentation do you wish for?
At the end of the session, someone asked the question “If you arrived on a project, what documentation would you wish to be there?”. The image contains the list of what we wanted.
We quite liked to have an installation manual and documentation about the development environment, to be able to see the application and get stuck in developing some new stuff. To understand the big picture, we like to see the “system on one page” and some explanation of all the (seemingly) weird decisions that have been taken during the project.
For people outside of the development team we recommend an operations/maintenance manual, which contains all the information you need to keep the application running. Some users might need a user manual or online help.
Acceptance testing documentation
What I’m currently struggling with is: “How can we test the quality of documentation? Can we write acceptance tests or fit criteria beforehand to drive the writing? TDD: Test Driven Documentation?”
Answers on a postcard…
Well, task-based documentation can be a very effective and efficient approach to fulfilling the needs a project’s stakeholders have regarding documentation. As such, one could conceive “acceptance tests” as scenarios such as “User installs the software”, “New developer sets up his environment”, “User finds instructions for contacting the development team”, and so forth.
Lasse, you’re right. The test is quite easy for an installation manual.
For the other ones the test would be a bit more difficult, but feasible.
The only question we need to ask is “What do you expect to achieve (by writing this documentation)?” and then test for that goal.
Sometimes, if you ask that question, the best answer turns out not be documentation.