Space Properties

When documenting with the Maven Site Plugin accessing properties from the Maven POM file is a great feature. When we switched to Confluence as our central tool for documentation, this was the feature we missed the most.

The Maven Extension allows to import the properties and stores them as space properties. Now these properties are as easy to access within Confluence as they are within the Maven universe.

Use the Display Space Property Macro to access the value of a single property. Using the space property macro the value will always be drawn from the latest release. If you need to reference a value for a particular version, use the Display Document Property Macro and select the page that contains the property.

Import Artifact Metadata

The Maven Extension allows to import information from artifacts stored on a Nexus artifact server. This way making this metadata available from a Confluence space is very easy.

Besides the Metadata from the POM we also import other information, like the Maven Plugin Metadata (see projectdoc for Maven Developers). This includes build metadata that is generated as an XML file by the Buildmetadata Maven Plugin.

The extension allows to create projectdoc documents based on Maven POMs.

The POM information is imported either via the GAV reference or by providing the URL to a POM file.

projectdoc downloads the artifacts from the configured Nexus artifact repository and creates a space based on that information.

Link Artifacts

To create a link to an artifact on a Confluence page based on space properties, use the Nexus Link Macro.

This macro is part of the free Information Systems Extension.

Reference Elements of a Java API

The Information Systems Extension allows to reference elements of a Java API generated with Javadoc. This is not a feature that is provided by the Maven Extension, but it may be handy for developers that created the API for their libraries or frameworks with the Javadoc Maven Plugin.

com.example.something.MyClass

com.example.something.MyClass.aMethod()

com.example.something.MyClass.aMethod(java.lang.String, java.lang.Class)

Transclude Fragments

The Information Systems Extension allows to tranclude from files stored on a remote server. With macros provided by this extension, parts of a document can be rendered as a code snippet. This includes diagrams or images created by the Enterprise Architect.

Make Information Accessible

While the Information Systems Extension allows reference information on remote information systems the Web API Extension makes information in Confluence spaces available to remote information systems.

This may make it easier for teams to provide properties via Confluence (for instance with the Document Properties Marker Macro or the Document Properties Supplier Macro) and consume them via a REST API from remote servers.

Documentation

There are a couple of free add-ons to help software development teams to document their products and projects.

Dynamic Lists

Dynamic lists are link lists that are defined by a query. This is certainly not a feature that is only relevant for Developers using the Maven Extension. But it is so helpful to create an easy navigateable documentation that we mention it here.

The Display Table Macro (and its cousins) is used to define a query on projectdoc documents and to select properties (and sections) from those documents. This makes it easy to list links to related resources if these resources are providing tags in the form of document properties. The Document Properties Marker Macro (and its cousins) allow to define those properties.

Link Servers

In some projects, servers are a moving target. The Information Systems Extension provides means to define remote resources as space properties and generate links via the autoconvert feature. Once a server moved, all links to that server can be updated in one place.

Deploy Artifacts

To create spaces for Java or Maven projects, follow the following steps.

The following add-ons are available on the Atlassian Marketplace:

1. Install the projectdoc Toolbox (commercial)
2. Install the Maven Extension (free)
3. Optional: Install the Information Systems Extension (free)
4. Install the Core Doctypes Add-on (free)
5. Install the Software Development Doctypes (free)

Then install either of the two doctype add-ons (or both):

1. Doctypes for Maven Developers Add-on (free)
2. Doctypes for Java Developers Add-on (free)

Configuration

To start your documentation, follow these steps:

1. Configure the infrastructure for Maven
2. Create a space with a Space Blueprint provided by one of the doctype add-ons

Get started

To get started, use the following information:

1. projectdoc Introduction
2. Introduction for new Users
3. Hands-on Tutorial