A document is considered to follow the agile principle if it is valuable, essential, and created or updated just-in-time. A documentation is created and maintained in an agile way, if all its documents follow this practice.
Agile methods are not opposed to documentation, only to valueless documentation.Michael Nygard. Documenting Architecture Decisions. 15. November 2011
The agile manifesto states that running software is more valuable than comprehensive documentation. So comprehensive documentation has value. But there is no hard-and-fast rule of how much documentation does meet the expectations of all stakeholders. In order to get it right we need a couple of rules for guidance, create valuable increments, and then iterate.
We categorized Agile Documentation as a practice and not as a principle. The reason for this is that the structure presented here is to complex to be a principle. One violated aspect of a principle is that it must not be further reducible. Therefore it needs to be considered a practice.
The whole site is dedicated to the topic of agile documentation. However we consider this practice a valuable tool since it focuses on the three main aspects to get started with. In our view everything else on this site still applies to agile documentation, but the structure described here is simply the starting line for working on documentation with an agile mindset.
Agile documentation requires that each document is valuable, essential, and created or updated just-in-time.
Teams need to determine the information needs of the stakeholders and provide the necessary information accordingly.
Therefore the first step for creating a document is the search for a stakeholder. Better yet, stakeholders identify their information need by themselves and ask the team for documentation. So there is at least one stakeholder required to justify the existence or maintenance of a single piece of documentation. This makes sure that at least one stakeholder values the document or knows an audience that values it.
These stakeholders with an information need typically know exactly what they need to know. This way the document can be adjusted to exactly match this need. Create an essential instead of a comprehensive documentation.
Last but not least documentation quickly gets out of sync with reality. Time runs forth and a document needs to be maintained to keep up with the pace of time. Therefore it is wise to wait for creating documents until they are needed. This keeps the maintenance costs low. In order to deliver documents just-in-time, teams need to employ automation and single sourcing to create documents quickly.
- The documentation responds to actual information needs. Every document is a liability. To reduce the amount frees resources to be spent in more relevant issues, such as working software.
- Maintenance cost is reduced if every document created is known to be still relevant.
- When documents are explicitly requested, they are more valued than documentation that is assumed to exist.
- To deliver just-in-time needs tooling and training. This is a serious investment.
- Stakeholders need to express their information needs. This may be difficult for some people. Teams need to provide support do define these requirements with stakeholders.
The following practices are related to this practice.
For more information regarding this practice please refer to: