This is the third in my Deep Agile Embedded Panel Questions series. The question is:

We had a team doing agile. To them that included not doing any documentation. We need documentation once we go into maintenance. Is doing documentation allowed in Agile?

The short answer is yes. Agile does allow documentation. Do you think agile is a totalitarian dictator? 🙂

Agile does not prescribe any documentation. That is very different from not allowing documentation. Each product’s and project’s needs are different; one size does not fit all. Teams have to decide for themselves what their documentation needs are.

That said, it’s a challenge to decide the documents to write. Documents are expensive to write and maintain. I suggest you do not write the document that page 347 of the process manual requires unless it survives the 5 whys.

1. Why do we write the TLA document?

   Because is says so on page 347 of the SQAPM.

2. Why is it in the SQPM?

   Because its always been there. (ridiculous answer, need to find real answer)

3. Why was it there in the first place?

   Because of the problems with TLA during maintenance.

4. Why is TLA needed during maintenance?

   Because testers don’t know TLA.

I think you get the idea. You might need more than 5 whys in this case, but you’ll get there.

The underlying thought is to know why the document is needed and why it is valuable. It can be helpful to know who is the customer for the document, how they plan on using it and when is it needed.

You might find some documents you currently write do not add value directly. View those documents as waste. The cheapest document is the one you do not write. When you decide the document is needed, look for less wasteful ways of creating it. Look for alternatives to narrative text. For example, automated unit tests provide very valuable documentation. The tests show how the code is used and they verify that the code meets the requirement expressed in the test.

Write a document when

• there is value in the document
• there is a business need
• there is a regulatory need
• there is a contractual need

If you can’t live without the document, you write it. Find an inexpensive way to create the document. Usually that means write it later, when you know more. Avoid writing too much into a document in anticipation of what you might do. Writing documents in anticipation usually results in considerable churn as reality strikes. The document will have to be revised later. A co-located team can effectively use a white board, note cards and each other to keep a design in progress in full view.

A common situation I’ve seen is the need for design documentation for maintenance, remote developers, inter-team collaboration, or outside reviewers. These documents can be valuable. They can be built more cheaply if you document what you did, rather than document what you anticipate doing. The documents written in anticipation often (read always) need to be revised as the realities of implementation face you. Writing a document later, once the important ideas have been discovered and tried, is more efficient.

If approval is needed to proceed on an anticipatory design, the process has built in delays that waste valuable time. Have some experienced designers on the team so the team goes the right direction in the first place. Document and review what works, not what you think might work.

Try this approach to growing a design document:

• Establish an architectural vision early in the project. Document it lightly, lighter than you normally do. You could use a hand drawn sketch that gets photo copied, or a couple electronic sketches with a brief overview.
• Keep it high level. Like a high level roadmap that helps navigate the design.
• Avoid including too much detail. When you plan a cross country trip, too many details can get in the way. This document could have a long life if you keep it conceptual.
• During each iteration evolve the design.
• At the end of the iteration write up the architecturally significant ideas that were created, documenting what was built, and tested.
• Keep the additions to the document high level. It will be more stable. It won’t get yanked around by little changes in detail. To be more specific, don’t create detailed function signatures for an API. You might name representative API functions and parameters, but don’t worry too much about the exact types being passed or returned. That can be done in the code and tests.
• Use automated unit tests to document the details; they also hold the behavior steady.
• Review what was built, rather than what is anticipated. This takes the review process off the critical path.