Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Section
Column
Document Properties Marker
overridefalse
Short DescriptionAgile 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. 
Doctypetopichide
NameAgile Documentation 
Parent
Parent Property
propertyParent
property-nameName
 
Audience
Name List
doctyperole
render-no-hits-as-blanktrue
render-list-as-comma-separated-valuestrue
namesDocumentation Architect, Documentation Gardener, Author, Template Author
propertyAudience
empty-as-nonefalse
 
Level of Experience
Name List
doctypeexperience-level
render-no-hits-as-blanktrue
namesAdvanced Beginner
propertyLevel of Experience
empty-as-nonefalse
 
Expected Duration

20 min

 
Subject
Name List
doctypesubject
propertySubject
 
Categories
Name List
doctypecategory
propertyCategories
 

Tags

Tag List
render-list-as-comma-separated-valuestrue
namesagile, documentation, wiki, Confluence, projectdoc Toolbox, projectdoc, transclusion, dynamic list, autolist, space properties, metadata
propertyTags

 


Iteration
Iteration
valuefilled
hide
Type
Name List
doctypetopic-type
render-no-hits-as-blanktrue
namesTip
propertyType
 
Sponsors
Name List
doctypestakeholder
render-no-hits-as-blanktrue
propertySponsors
 

Sort Keyhide
Section
show-titlefalse
titleDescription

Effective communication is an essential part for the success of a software development project. Documentation is that part of the communication that needs to be written down. There are several reasons for writing things down.

  1. Scaling - feeding with information in parallel
  2. Communication for dislocated teams (in space and time)
  3. Communication with one's future self (journals)
  4. Support learning at an individual pace
  5. Learn more about the subject by having to put it in words

Writing is not an easy task.

Quote External
authorWilliam Zinsser
author-urihttp://www.williamzinsserwriter.com/
sourceOn Writing Well

Writing is hard work. A clear sentence is no accident. Very few sentences come out right the first time, or even the third time. Remember this as a consolation in moments of despair. If you find that writing is hard, it's because it is hard. It's one of the hardest things that people do.

Documentation of a software project is communicating important facts. Reasons for decisions, the quality goals, the requirements, the architecture, all this (and more) typically needs to be communicated. This could be overwhelming to create and a nightmare to maintain.

Agile documentation for the rescue!

Column
width300px
Panel
titleContents

Table of Contents
outlinetrue
indent10px
excludeAgile Documentation
stylenone
 

Panel
borderColorDarkred
bgColorlightred
titleColorwhite
titleBGColorDarkred
titleAgile

This article does not discuss or explain basic agile values, principles or techniques. It assumes that the reader is familiar with this approach.

If you want to learn about agile, we recommend to start by reading the Agile Manifesto.

Section
titleWhat is this all about?

Teams may fall in the trap to craft islands of beautiful documents. These documents require a lot of resources. Not only when creating them, but especially in their maintenance phase. Since writing maintainable documentation is not easy, some teams may try to go without. Very few teams are even reading "Working software over comprehensive documentation" (see Agile Manifesto) falsely as "Do not write documentation".

Section
 
Column
width30%


Column
width40%
Panel
borderColorDarkgreen
bgColorlightgreen
titleColorwhite
titleBGColorDarkgreen
titleAgile documentation is about
  1. essential and
  2. valuable information
  3. that teams create just-in-time
 
Column
width30%


References Box

We are quoting Documentation in Agile: How Much and When to Write It? by Ben Linders which takes this to the point. Ben Linders references Ashish Sharma as orginal source: Essential, Valuable, Timely Documentation.

The trick is not to strive for comprehensive documentation, but sticking to the information that is essential. This reduces maintenance cost and the chance to invest in something nobody needs. Therefore it is first of all very important to have access to the stakeholders who are actually in need for information. Before starting a documentation effort, find these stakeholders. These stakeholders will know their information need and this is what the documentation should essentially talk about. Last but not least the stakeholders can tell when this information is actually required. Since projects and products are moving it is usually beneficial to defer the investment to the last responsible moment - creating it just-in-time.

To create information just-in-time there need to be some form of automation and reuse. This reduces creation and maintenance effort. There is some information that cannot be derived from artifacts of a software development project. This is information like "why this project is important?". Automation will help to save time in some documentation work areas to have more time to invest in these often mission-critical areas.

...

Section
titleprojectdoc Support
Section
Column

The goal is to help teams to create essential and valuable information for the stakeholders of a project just-in-time.

The PDAC1 for Confluence supports Agile Documentation by this features:

  • Team Communication
    • Sponsor
    • Iteration
    • Audience
    • Short Description and Description
  • Automation and Reuse
    • Transclusion
    • Autolist
    • Document Properties
    • Space Properties
    • Metadata Import
    • Remote Information Systems
Column
Panel
borderColorDarkred
bgColorlightred
titleColorwhite
titleBGColorDarkred
titleResources on Agile Documentation

This article has a focus on introducing the PDAC1 and how it supports Agile Documentation.

If you are looking for more information on Agile Documentation in general, we recommend the following resources:

Section
titleTeam Communication
Section
Column

Reminding team members to focus on real stakeholder needs is very important. Stakeholders in this definition is everyone who takes interest in the success of the project. This includes the project managers, the team, and first and foremost the users and customers. Communicating the purpose of a particular document, what it costs to be created and maintained, is valuable information. Every document is a liability and creating one should be considered and discussed.

The PDAC1 provides properties for many document types that communicate the sponsor and the current status of a document.

  • Sponsor - defines who is willing to invest into creating a document
  • Iteration - communicates the state of a document in the process of getting published
  • Audience - specify who this information is targeting at
  • Short Description - what the audience will learn from the document
  • Short Descriptions may be further detailed in the Description section of a document
Column

If you want to make this information more formal, the sponsor may choose to create a Charter document. This document describes the purpose of a document and may be considered metadata for one or several documents. It provides additional information by these document properties and sections:

  • Timebox - the amount of time to invest into the creation of the document
  • Documented Information Type - whether it is a status report or it needs to be maintained
  • Experts - a list of stakeholders to consult to create the documentation
  • Documentation Root - the reference to the created documentation
  • Mission - more details about why this documentation is important
  • Tools - a list of tools to use to create the documentation - including the tools that are documented
  • Information - the information to be drawn from the created documentation

But this formal approach may be overkill for most projects. It could be used as a tool to get agile documentation started and help team members to focus on the sponsor's basic goals. Think of the Charter document as a worksheet to add interesting meta-information as you work on the documentation, not as a template to file to a folder.

Section
titleAutomation and Reuse
Quote External
authorMike Clark

Automation will give you back something you don’t have enough of: time.

Automation and reuse especially supports teams to create documentation just-in-time. The PDAC1 provides tools to save time, mostly by reducing the amount of manual work and making it easy to reuse information by the following techniques.

Section
titleTransclusion
Section
Column

Transclusion allows to use (possibly parametrized) information in different contexts. Not only reduces this feature the cost by reusing what is already there, it also reduces the maintenance costs since changes can be applied in only one location.

Tour
render-as-definition-listtrue
replace-title-with-nametrue
Column

Section
titleAutolist
Section
Column

Adding new information must not require to edit existing documents. This is the Open/closed Principle for documentation. Documentation should be open for extension but closed for modification. Each new document is an extension of the whole documentation. By adding tags and other meta-information, the new document should be listed in existing contexts automatically. This is done with automatic lists, which are sometimes called dynamic lists.

With these automatic lists teams are able to provide alternative views on their documentation with minimal maintenance costs. Simply define queries on metadata and list all information for this context in one document.

Tour
render-as-definition-listtrue
replace-title-with-nametrue
Column

Section
titleDocument Properties
Section
Column

Document properties define document metadata and information about the documented entity. This information can be accessed to be displayed or to control the rendering of sections. Again, the information is specified in one place and can be reused by transclusion.

Tour
render-as-definition-listtrue
replace-title-with-nametrue
Column

Section
titleSpace Properties
Section
Column

Space properties make information accessible and therefore reusable within a space or a hierarchy of spaces. This reuse makes it easy to change a value - such as a version information - in one place and have other information updated immediately.

Example Box
titleVersion Information

The version affects some information in a library for Java documentation. Suppose that a team wants to render the dependency snippet of a POM, activate the properties defined in the POM and render the version on the homepage of the library. The version is used - in this example - at three different locations. Since they all depend on the space property for the version information, all three locations are updated once the value for the version property is changed.

Tour
render-as-definition-listtrue
replace-title-with-nametrue
Column

Section
titleMetadata Import
Section
Column

Metadata can be derived from multiple artifacts created by a software development team. This includes classical metadata like dependencies or project properties, but also test result reports or error codes documentation. Since this information is already available in different locations, it has to be made available from within the documentation system.

The PDAC1 allows to import information as space properties and makes it easily accessible for team members creating documents.

Tour
render-as-definition-listtrue
replace-title-with-nametrue
Note Box
titleExperimental Feature

Please note that we are currently experimenting with this feature. Most of the tools are currently in their beta stage.

Column

 

Section
titleRemote Information Systems
Section
Column

While it is important to be able to import metadata into the documentation system, some resources may be better stored in specific information systems.

For instance

  • a team may use an artifact repository to manage the artifacts of a project.
  • a team may create an API documentation with a rich user experience.
  • a team may need to provided access to all forms of living documentation (for instance test results or online system information).

In these cases it seems not feasible to reproduce the information in the documentation system, but rather link to it. But these links must not be maintained individually. By using space properties, the links may be updated to point to new locations by adjusting the configuration in one location.

Tour
render-as-definition-listtrue
replace-title-with-nametrue
Column

 

Section
titlePrerequisites

...

Section
titleResources

More information on projectdoc:

Tour
render-as-definition-listtrue
replace-title-with-nametrue
Piwik Set Multiple Custom Variables
NameValue
Departmentprojectdoc
Categoryprojectdoc-tip
Typehowto