Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Document Properties Marker
overridefalse
Short DescriptionA 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.
Doctypepatternhide
NameAgile Documentationhide
Short Name
Parent
Parent Property
property-nameName

Audience
Name List
doctyperole
propertyAudience

Subject
Name List
doctypesubject
propertySubject

Categories
Name List
doctypecategory
propertyCategories

Tags
Tag List
propertyTags

Domain

Name List
doctypepattern-domain
namesDocumentation
propertyDomain


Type

Name List
doctypepattern-type
namesCollaboration
propertyType


PrinciplesYAGNI Principle, KISS Principle, Teamwork
Iteration

Iteration
valuefinished

hide
Sort Keyhide
Section
titleDescription

Section
titleExample

Section
show-titlefalse
titleContext
Quote External
source-urihttp://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
authorMichael Nygard
author-urihttp://thinkrelevance.com/team/members/michael-nygard
sourceDocumenting Architecture Decisions
source-date15. November 2011

 Agile methods are not opposed to documentation, only to valueless documentation.

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.

Note Box

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.

Section
show-titlefalse
titleProblem
Panel
How can teams create documentation following the agile principles?
Section
titleStructure

Agile documentation requires that each document is valuable, essential, and created or updated just-in-time.

Section
titleValuable

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.

Section
titleEssential

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.

Section
titleJust-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.

Section
titleAdvantages
  • 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.
Section
titleDisadvantages
  • 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.
Section
titleVariants

Section
titleSubordinate Patterns
Display Table
doctypepattern
render-no-hits-as-blanktrue
selectName, Short Description
restrict-to-immediate-childrentrue
sort-bySort Key, Name
Section
titleRelated Practices
intro-textThe following practices are related to this practice.
Tour
render-as-definition-listtrue
replace-title-with-nametrue
Section
required-permissionswrite-access
titleNotes

Section
titleReferences

Section
titleResources
intro-textFor more information regarding this practice please refer to:
Tour
render-as-definition-listtrue
marker-column-property-nameTitle
replace-title-with-nametrue
TitleShort Description
Agile ManifestoThe 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 DocumentationArticle by Ashish Sharma on Agile Documentation (2013) requiring it to be essential, valuable, and timely.
Documenting Architecture DecisionsBlog article by Michael Nygard on decisions and agile software development (2011).
Dokumentation in agilen ProjektenBook by Andreas Rüping (2013, in German) where he defines agile documentation as "bedarfsgerechte Dokumentation" (requirement orientated documentation).
Agile DocumentationBook on agile documentation (2003, in English) by Andreas Rüping.
Agile/Lean Documentation: Strategies for Agile Software DevelopmentThis article by Scott Ambler explores agile and lean philosophies towards documentation within IT organizations.
SE-Live 2015: Gerhard Müller: Agile DokumentationIn 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
Piwik Set Multiple Custom Variables
NameValue
Departmentagiledoc
Categorypractice
Typedocumentation