Disciplined Agile

Agile Documentation Strategies

An important part of our solution is deliverable documentation, the kind of documentation needed by our stakeholders to work with, operate, and sustain the solution. This may include system overview documentation, user guides/help, training manuals, and operations guidelines, etc. There are several agile documentation strategies to keep in mind:

  • Invest in quality over documentation. The better designed our solution is, the easier it will be for stakeholders to understand it, and therefore generally less documentation will be required.
  • Write documentation that is just barely good enough (JBGE). When we do create documentation it should be JBGE, or just barely sufficient, to fulfill the needs of our stakeholders and no more. Any investment in an artifact to make it more than good enough is a waste, and sufficiency is determined by the customer of the document, not the producer. Keep your documentation concise.
  • Document stable concepts, not speculative ideas. Speculative ideas, such as requirements, are likely to evolve over time. This in turn requires you to update your documentation. Whenever possible, wait until the material that you are describing is stable before you capture it in documentation.
  • Find better ways to communicate. If the purpose of a document is to communicate information to others, it is important to recognize that detailed documentation is one of the least effective means to accomplish that purpose. You have other communication options available to you to choose from.
  • Recognize that you need some documentation. A common, and unfortunately enduring, misunderstanding about agile is that agile teams don’t write documentation.  Nothing could be further from the truth, and there is a wealth of information about agile/lean documentation strategies available to you that are leveraged within the Disciplined Agile (DA) tool kit.
  • Work closely with stakeholders. The only way we can write effective documentation is if we know what our stakeholders need and how they will work with the documentation that we produce. Effective documents tend to be single purpose and targeted at a specific audience. Figure 1 summarizes the CRUFT formula for calculating the effectiveness of a document as a percentage, and please note that 4 of the 5 factors rely on the customer of the document.

Effectiveness of a document = C*R*U*F*T 

Where:

C = The percentage of content that is correct
R = The chance the document will be read
U = The chance that the content will be understood
F = The chance that the advice will be followed
T = The chance that the advice will be trusted

Figure 1. Calculating the effectiveness of a document.

February 2022