Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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 few comprehensiveness 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.

projectdoc-box-note

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.

projectdoc-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

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.

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.

Note Box

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

...