Integrate information from different sources into your documentation using Confluence and the projectdoc Toolbox.
This is a short outline on how to bring living documentation to Confluence - the team collaboration platform - with the projectdoc Toolbox.
We will first define what living documentation is and then show how the tools in the projectdoc Toolbox support it. The journey will take us from the source code artifacts, where the information specified, to the Confluence page, where this information is displayed.
This approach can be used - for instance - to document error and response codes, create examples of usage patterns of APIs, or to expose project and product properties, such as build information or configuration properties.
Process
This definition and principles in mind we outline a process based on Confluence and the projectdoc Toolbox where information is
- gathered from the source,
- refined, packed, and finally
- fed to the team collaboration platform.
The information may be
- copied (imported) in case it is frozen (that is: a release with a version number has been created),
- transcluded from remote information systems, or
- referenced in remote information systems.
This way the documentation is
- reliable - it is in-sync with the information in the source artifacts
- created at low-cost - it is integrated automatically
- collaborative - it is available in the team collaboration platform so that each stakeholder has access to (directly or indirectly)
- insightful - every stakeholder provides feedback and is able to refine information by adding new views on the subjects
From the Source
The farther documentation is away from the source code, the more likely it is that it is out-of-date and therefore plain wrong. It is beneficial to keep all information as close to the source as possible. This makes it easier for the development team to reflect changes to the source code directly to the documentation in the source file.
The information may be available in plain configuration files, like the Maven POM file or deployment descriptors such as the web.xml.
Often the information is attached to the source code by the use of annotations (see Java Annotations). The annotations typically have impact on the runtime behavior. So changing an annotation directly takes effect in the execution of the software.
Information may be added as comments, especially as API documentation, such as Javadoc.
Finally information may also be gathered from types (such as interfaces) or members (fields and methods).
Here are some examples for tools and libraries that add information to the source code.
Bundle Reports to Artifacts
Some information is automatically bundled with the generated artifact during the build process.
- The Java Manifest file is stored to the META-INF folder of the JAR
- Buildmetadata Maven Plugin collects build time information and adds it as a properties or XML file to the META-INF folder
- The Maven Plugin Descriptor is added to the META-INF folder
- The OSGi Bundle Repository of a Confluence add-on is stored in the root folder of the OBR file
For information that is not automatically attached, the Projectmetadata Maven Plugin allows to create an artifact with any information attached. This artifact is then added to the artifact server for reference. The inclusion of report artifacts is based on descriptors. The plugin provides a number of standard descriptors and allows to define custom descriptors to attach additional formats.
Make available
The following techniques make the report information available on the team collaboration platform.
Import Artifacts
Import static information to a space by referencing a POM file or its GAV coordinates.
- Create a space to document Maven plugins using projectdoc for Maven Developers
- Create a space to document a Java library using projectdoc for Java Developers
- Use the Version Doctype of the Core Doctypes to add new versions to an existing space
Experimental
The import is based on the Maven Extension which is currently experimental.
We already use it to document our own products. Be aware that we currently only cover some basic use cases.
Use in your Documents
Now let's access the provided information.
Imported Information
Static imported information can be easily accessed using the Display Space Property Macro and Display Document Property Macro (or it's cousins).
Real-Life Project
The smartics Enforcer Rules for Maven is based on the Java space template and has imported a number of versions via its Maven POM file.
The screen shot shows an excerpt of the properties from the project's POM.
Refer to Space Properties and Using Space Properties for more information on space properties and to Document Properties for more information on document properties.
Remote Information
Information on remote systems can be easily transcluded or referred to using macros of the Information Systems Extension.
- Reference Javadoc API reports with the Javadoc Link Macro
- Transclude diagrams on an Enterprise Architect repository using the Enterprise Architect Image Link Macro
- Reference Artifacts on an artifact repository with the Nexus Link Macro
- Reference or transclude remote resources with the System Image Link Macro, System Transclusion Macro, or System Link Macro
References can be easily made with plain Confluence links. The advantage of the macros is that they use space properties to construct the URL to a remote resource. If resources on a server move to another address, the base URL can be easily updated in one place. All links based on this URL are automatically updated.
Export - optionally
Not all stakeholders may have access to the team collaboration platform. In this case wiki pages can be exported to Word or PDF using the Scroll Office Add-on by K15t. 
The exported page is then treated as a record that does not demand to be updated. But it can easily be transferred to remote parties.
Summary
In our short tour we have introduced tools to put information to source files and build tools to aggregate and export this information.
With the use of Confluence as the information hub and the projectdoc Toolbox this information can be easily accessed by the team to write documentation in an agile way!
Writing documentation based on living documentation is actually quite easy and a lot of fun!
Give it a try!
