projectdoc Toolbox

Add-on to extend projectdoc for Confluence with Maven Tools.

Categories

Tags

Version

2.0

projectdoc Toolbox

2.0

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.

Since version 2.0 this extension provides a web API to import version information from an artifact built with Maven.

Contents

Beta Status

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!

Features

Here is a list of features the projectdoc Toolbox provides for software developers using Maven.

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.

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 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.

Java Elements in Javadoc

To reference the a class, specify the name of the class like this:

com.example.something.MyClass

The following example references a method aMethod():

com.example.something.MyClass.aMethod()

Here an example referencing a method aMethod(String, Class<?>) with generics:

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

Note to specify the parameters fully qualified and that generic type parameters or wildcards are not part of the reference.

Javadoc Link Macro: Links API documentation pages for Java elements.
System Transclusion Macro: Transclude content from a resource from a remote system.
HTML Snippet Macro: Transclude HTML content from a remote server.

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.

System Transclusion Macro: Transclude content from a resource from a remote system.
Text Snippet Macro: Transclude text content from a remote server.
System Image Link Macro: Renders an image transcluded from a remote server.
Enterprise Architect Image Link Macro: Renders an image generated from an Enterprise Architect diagram, transcluded from a server.

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.

Doctypes for Software Development: Provides doctypes to create documentation in software development projects. The focus is on documenting the architecture of the product, but it includes templates for other software development documentation requirements as well.
projectdoc Add-on for arc42: Provides doctypes to document a system or software architecture based on the arc42 Template.
Doctypes for Agile Planning: Provides doctypes to collborate with your team. Run iterations and record discoveries that may be of interest at the end of the iteration or for even later reference. Quick notes are more easily added as records to the team's space than to the official documentation tree. Defer the talk to the documentation architect to the end of the iteration (if the discovery is still of interest).
projectdoc Developer Diaries: Provides doctypes to organize the developer's work by the employment of a diary. Take you personal planning and professional records to the next level!
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.

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.

Installation

Deploy Artifacts

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)
Install the Software Development Doctypes (free)

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

Doctypes for Maven Developers Add-on (free)
Doctypes for Java Developers Add-on (free)

Configuration

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

Get started

To get started, use the following information:

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.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java