Add-on to extend projectdoc for Confluence with Maven Tools.
All team members needs to select their set of tools to do their work. Therefore, for instance, software developers should not be told to document their work in a wiki. If they are more effective to do their documentation work in a markup language file, stored on a Git repository, then they should use this approach. But each team member needs to have access to all the information relevant for the success of a project or product. This includes all members in their different roles, such as marketing specialists, managers, UI designers, delivery experts and so on. Therefore a wiki is a great tool to make all this information provided by all the stakeholders accessible through one access point.
Confluence, as a team collaboration platform, is designed for this task.
The Maven Extension for Confluence does not provide all forms of import for all kinds of information. In fact, this is just a start. But we think that this approach is very valid to really include all stakeholder and their concerns to work successfully as one team.
Please note that this extension is in beta status. We are experimenting with the integration of Maven artifacts and not everything is running as smoothly as you would expect from the final release.
We would be happy to receive your feedback about what you like most and would love to hear what features your would like to be improved!
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.
Fan of Metadata?
If you are a fan of metadata you may have a look at the Projectmetadata Maven Plugin. This plugin for Maven allows to package metadata to be stored on an artifact server.
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.
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.
Java Elements in Javadoc
To reference the a class, specify the name of the class like this:
The following example references a method
Here an example referencing a method
aMethod(String, Class<?>) with generics:
Note to specify the parameters fully qualified and that generic type parameters or wildcards are not part of the reference.
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.
There are a couple of free add-ons to help software development teams to document their products and projects.
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.
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.
To create spaces for Java or Maven projects, follow the following steps.
Prior to version 1.11 of the projectdoc Toolbox the two extensions are part of the projectdoc Toolbox add-on.
The following add-ons are available on the Atlassian Marketplace:
- Install the projectdoc Toolbox (commercial)
- Install the Maven Extension (free)
- Optional: Install the Information Systems Extension (free)
- Install the Core Doctypes Add-on (free)
Then install either of the two doctype add-ons (or both):
To start your documentation, follow these steps:
- Configure the infrastructure for Maven
- Create a space with a Space Blueprint provided by one of the doctype add-ons
The following doctype add-ons are based on the Maven Extension.
- Core Doctypes
- Provides a basic set of doctypes to create agile documentation.
- projectdoc for Java Developers
- A collection of blueprints for Confluence to create and work with documentation for Java projects.
- projectdoc for Maven Developers
- A collection of blueprints for Confluence to create and work with documentation for Maven projects.
All examples shown are based on one of these doctype add-ons. The Maven Extension does not provide any macros, doctype or space blueprints.
- Maven POM Import
- Import project information from Maven POM files. Provides information about required configuration to get this import running.