- Created by Robert Reiner, last modified on 05. Jun 2017
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.
- Domain
- Type
- Principles
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.
Structure
Agile documentation requires that each document is valuable, essential, and created or updated just-in-time.
Valuable
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.
Essential
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.
Just-in-Time
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.
Advantages
- 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.
Disadvantages
- 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.
Related Practices
The following practices are related to this practice.
- Know your Mission
- Use charters to define the purpose and benefit of each document. State the expectation of the stakeholders involved.
- Last responsible Moment
- Defer a decision to the last responsible moment is also a risk-reducing technique for writing documentation.
- Focus on Content
- Make it easy for knowledge workers to focus on content and remove the need to define the document structure and formatting on a ad-hoc basis.
- Single Sourcing
- Reduce redundancy by having one source of truth for each information. This way the written information is more easily reusable in other documents and - which is even more important - it is referenceable. Single sourcing demands automation.
Resources
For more information regarding this practice please refer to:
- Agile Manifesto
- The Agile Manifesto for software development.
- Documentation in Agile: How Much and When to Write It?
- Article on Agile Documentation by Ben Linders on infoq.com (2014).
- Essential, Valuable, Timely Documentation
- Article by Ashish Sharma on Agile Documentation (2013) requiring it to be essential, valuable, and timely.
- Documenting Architecture Decisions
- Blog article by Michael Nygard on decisions and agile software development (2011).
- Dokumentation in agilen Projekten
- Book by Andreas Rüping (2013, in German) where he defines agile documentation as "bedarfsgerechte Dokumentation" (requirement orientated documentation).
- Agile Documentation
- Book on agile documentation (2003, in English) by Andreas Rüping.
- Agile/Lean Documentation: Strategies for Agile Software Development
- This article by Scott Ambler explores agile and lean philosophies towards documentation within IT organizations.
- SE-Live 2015: Gerhard Müller: Agile Dokumentation
- In this talk (23.4.2015, Software Engineering Live) Gerhard Müller provides an introduction to agile documentation and explains how it supports software development. Especially the overview over a wide range of ideas and tools to be employed in the context of agile documentation is very helpful. This talk is only available in German.
- Agile Documentation
- Agile documentation is not another buzzword. There is actually a set of rules to follow which will lead to meaningful documentation. Writing helpful documentation is not easy, but it gets a lot easier with the agile mindset - and with the projectdoc Toolbox.
