Provide a standard documentation for users of a library for Java.

Categories: / Product Documentation

Teams using continuous deployment may choose to create libraries to modularize their code base. Each library is a product of its own with its own release cycle. Especially if the library is made public available, a sound and similar structure of the documentation helps developers to find information on how to use this library easily.

To create a user documentation for a library for Java the projectdoc for Java Developers Add-on for the projectdoc Toolbox provides tools to import information from a Maven POM file. This way all properties specified by the developers are accessible as space properties by authors of the documentation.

Experimental Add-on!

The projectdoc for Java Developers Add-on is available on the Atlassian Marketplace and on Bitbucket. It is still considered to be experimental. So expect to encounter some rough edges.

Please get in touch if you have suggestions for improving the add-on or fork it on Bitbucket!

Example for a Library Documentation with Confluence and the projectdoc Toolbox

This approach does require to create a Maven Site with all reports (for example Javadoc Report, Source Code Report, or Changes Report) and link to or transclude from this information. The Information Systems Extension provides macros to access information from remote servers.

Resources

Information Material

The following list of resources provides background information on creating and working documentation for Java libraries based on the projectdoc Toolbox for Confluence.

Resource	Short Description	Type
Hands-on Tutorial	Get started with the projectdoc Toolbox: learning by doing	topic
Doctypes Introduction	A gentle introduction to page blueprints provided by doctype add-ons. The page blueprints are grouped semantically to make it easier for users to build a conceptual mind map for them.	topic
Basic Concepts and Conventions for projectdoc	Concepts central to projectdoc. Things users have to understand to get the most out of using projectdoc.	topic
Using Space Properties	Space properties are defined for spaces and are accessed via the Space Property Macro. This tip goes into detail in how to use space properties with inheritence and extension pages.	topic
Space Properties	Lists the configuration options at space level.	topic
Information Systems Extension	Add-on to extend the projectdoc Toolbox to integrate remote information systems.	topic
Web API Extension	Add-on to extend projectdoc with an API to access on the web.	topic
Maven Extension	Add-on to extend projectdoc for Confluence with Maven Tools.	topic

Doctypes

The following doctypes (blueprints based on the projectdoc Toolbox) provided page blueprints to create documentation for a Java library.

Resource	Short Description	Categories
Property	Properties are part of the configuration options of a system.	/ Process / Implementation
Metadata	Metadata documents provide tables of simple key/value pairs. This information can be used as an aspect or as additional space properties to be available for reference on your wiki.	/ Document / Data
Version	Document a version of a product or service.	/ Document / Data
Artifact	Document requirements you impose on artifacts. Artifacts are created by processes defined and used by the team. This includes assemblies created by the build process, source code artifacts or reports.	/ Process / Design / System / Element
Code	Describe the codes that are part of the product's API.	/ Process / Implementation
Interface	Interfaces document how elements of the system communicate with elements of this and other systems.	/ Process / Design

Macros

The following macros of the projectdoc Toolbox support creating or working with documentation for a Java library.

Resource	Short Description	Categories
Display Space Property Macro	Renders a space property value.	Display / Property
Display All Space Properties	Renders all properties referenced by the current space.	Development
Enterprise Architect Image Link Macro	Renders an image generated from an Enterprise Architect diagram, transcluded from a server.	Link / Information System
HTML Snippet Macro	Transclude HTML content from a remote server.	Link / Information System
Javadoc Link Macro	Links API documentation pages for Java elements.	Link / Information System
Nexus Link Macro	Renders a link to an artifact stored on a Nexus server.	Link / Information System
System Image Link Macro	Renders an image transcluded from a remote server.	Link / Information System
System Link Macro	Links to a resource on a server.	Link / Information System
System Transclusion Macro	Transclude content from a resource from a remote system.	Link / Information System
Text Snippet Macro	Transclude text content from a remote server.	Link / Information System

Related Use Cases

Resource	Short Description	Categories
User Documentation for Maven Plugin	Provide a standard documentation for users of a plugin for Maven.	/ Product Documentation
Software Architecture Documentation	Communicate the quality targets, context, and design drivers of your software architecture.	/ Volume

Space shortcuts

Child pages

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Resources

Information Material

Doctypes

Macros

Related Use Cases

About

Keep up-to-date!

Powered by