What documents should we produce?
Produce two kinds of documents:
- Whatever the team needs to have for their own purposes;
- Whatever the project's masters ask for.
The team’s own needs are often pretty light. They might include pictures and lists on the whiteboard, simple charts of various metrics, perhaps a wiki containing odds and ends of information figured out or tricks learned.
The documents requested by the customer / product owner can be whatever they want. The single most important trick is to treat them like features: they will be listed in the iteration plan as features to be built, they will be estimated and costed just like any software feature. This leads to important conversations like this one:
Customer: I'd like you to keep a document up to date describing the design of the system, all the classes and their APIs, with at least twenty-seven eight by ten color glossy diagrams with circles and arrows and a paragraph on the back of each one explaining what each one is.
Team: No problem. We estimate that that will take about ten developer days to create the first time, and probably somewhat less to update every time you want it updated. It will still take developer days, of course, since it will grow as the system does. Just schedule an update whenever you want it updated.
Customer: Ten days??
Team: That's just an estimate, but based on what you've said, that's conservative. The twenty-seven eight by ten color glossy diagrams with circles and arrows and a paragraph on the back of each one explaining what each one is will require at least two hours each, so that's over a developer week right there. We can time box the effort to any duration you want, of course, or we can keep working on the document until you approve it, to get the actual time needed.
Customer: Could we make the twenty-seven eight by ten color glossy diagrams with circles and arrows and a paragraph on the back of each one explaining what each one is simpler?
Team: We would have thought so. What is the purpose of the twenty-seven eight by ten color glossy diagrams with circles and arrows and a paragraph on the back of each one explaining what each one is?
Customer: So that we'll know what the system is like.
Team: So that who will know?
Customer: Well, me, and you.
Team: We'll definitely be drawing any diagrams we need, over there on the whiteboard. And we can answer any questions you have, in person or in writing, whenever you want us to.
Customer: ... maybe we'll hold off on those diagrams a bit ...
Team: No problem. We'll write whatever we need automatically, and we'll write whatever you request, whenever you request it. We'll always give you a clear estimate of how long it will take, keep you up to date on how long it is really taking, as we do with any other feature, and we can of course time-box the effort if you prefer. Just request a document in the planning meeting, like you would any other feature.
Customer: Great, thanks, carry on.
Here are a few other articles relating to documentation and communication on Agile projects: