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.
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.
projectdoc Support
The goal is to help teams to create essential and valuable information for the stakeholders of a project just-in-time.
The projectdoc Toolbox 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
This article has a focus on introducing the projectdoc Toolbox and how it supports Agile Documentation.
If you are looking for more information on Agile Documentation in general, we recommend the following resources:
- Agile/Lean Documentation: Strategies for Agile Software Development and Best Practices for Agile/Lean Documentation - essays by Scott Ambler
- Agile Documentation - book by Andreas Rüping
- Specification By Example - book by Gojko Adzic, which introduces the notion of Living Documentation
Team Communication
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 projectdoc Toolbox 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
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.
Automation and Reuse
Automation will give you back something you don’t have enough of: time.
Mike Clark
Automation and reuse especially supports teams to create documentation just-in-time. The projectdoc Toolbox provides tools to save time, mostly by reducing the amount of manual work and making it easy to reuse information by the following techniques.
Transclusion
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.
Autolist
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.
Document Properties
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.
Space Properties
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.
Version 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.
Metadata Import
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 projectdoc Toolbox allows to import information as space properties and makes it easily accessible for team members creating documents.
Experimental Feature
Please note that we are currently experimenting with this feature. Most of the tools are currently in their beta stage.
Remote Information Systems
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.
