An example of an software architecture documentation based on the arc42 Template on Confluence 5 with projectdoc and the projectdoc Add-on for arc42.

This documentation is created with the free projectdoc Add-on for arc42 and the commercial projectdoc Toolbox for Atlassian Confluence.

This example is based on the HTML Sanity Checker Architecture Documentation created by the arc42 team using AsciiDoc (available on GitHub). This example shows the application of the arc42 Template to create the software architecture documentation for a standalone tool (batch- and command-line) that detects missing images, dead links, duplicate bookmarks.

How to document a Software Development Project is an introduction to start creating documentation with the arc42 Template on Confluence with blueprints.

For more information on the arc42 Template, please visit its homepage at arc42.org!

arc42 is owned by Dr. Peter Hruschka & Dr. Gernot Starke. For details on using arc42 for your projects please visit the arc42 website !

Based on the arc42 Template the

Software Architecture Documentation

for the HTML Sanity Checker

has been created.

projectdoc Add-on for arc42

The projectdoc Add-on for arc42 provides blueprints to bring the arc42 Template to the Confluence team collaboration platform for easy use.

So what is in for me using this add-on?

 Simply put:

Create by wizard, don't copy-paste

Create incrementally, clutter-free

Create by using modular content


The projectdoc Toolbox makes it easier for teams to create and maintain a modular documentation they can collaboratively work with. The arc42 Template allows to bring this modular information into a well-know structure. This enhances the usability of the architecture documentation since many software developers and architects know arc42.

Create by Wizard

projectdoc provides templates that help you document your software project that are not or only loosely related to architecture documentation.

 

If you have created the arc42 Space, the arc42 Template is already available in the space.

How to document a Software Development Project is an introduction to start creating documentation with the arc42 Template on Confluence with blueprints.

Create the SWAD

 

Create other Documents

The example shows two of more than 40 blueprints.

Clutter-free Views

A template helps authors to provide the content in a commonly defined structure. Documentation is created incrementally, therefore some of the sections of a template are added at a later time. To not bother the reader with sections that may or may not be added in the future, projectdoc allows the author to have the empty sections in the template for future use, but will only render them if they actually have content.

Here is an example:

Blackbox Document in Editor

The page contains in its properties and sections information about how to work with the template. The properties are defined with the Document Properties Marker Macro, the sections with the Section Macro.

Blackbox Document in View

The Blackbox in View Mode

Due to the Section Macro, the reader's view is not cluttered with sections without any information.

The metadata on the top of the page is provided with the Document Properties Marker Macro. Again, only properties that actually have a value are rendered.

Modular Content

The information that is relevant for the software architecture is added in separate wiki pages as documents. Therefore there are document types for stakeholders, roles, architecture decisions, interfaces, and many others.

The information is then transcluded into the arc42 template.

 

Transclusion of page fragments is usually slow. Therefore the Software Architecture Documentation refers to a structure to create the documentation collaboratively.

The SWAD (Single Page) is an alternative view on this document and typically used to be printed.

Get started with arc42 on Confluence with projectdoc in 4 easy steps!

1. Install the projectdoc Toolbox

The projectdoc Add-on for arc42 uses templates from the Core Doctypes for projectdoc (like Role or Stakeholder) and from the Software Development Doctypes (like Architecture Decision or View).

Both add-ons are available on the Atlassian Marketplace for free. Note that Atlassian Confluence and the projectdoc Toolbox have commercial licenses.

What is projectdoc for Confluence?

I have 1 minute! Why should I care?

The Problem

Lost in wiki space? Blank-Wikipage-Syndrome? Where to add? How to find? No fun anymore?

Wikis are a great way to add documents relevant for a software development project.

After a splendid couple of weeks the highly motivated team added plenty of information to this space.

And step by step

  • information is more difficult to find
  • new information is more difficult to add

The Solution

projectdoc tackles these issues by adding structure to

If you have 2 minutes ...

Watch our video introduction!

If you have some more minutes ...