Page History

Document Properties Marker

doctype	project
hide	true
extract-short-desc	true
render-as	definition-list

Doctype

project

hide

Name

HTML Sanity Checker Architecture Documentation

Short Description

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

Recently Updated

types	page, comment, blogpost, spacedesc
max	10
hideHeading	true
theme	concise

Section

Column

width	60%

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.

Content Marker

hide	true

Cheese

Column

width	40%

Panel

borderColor	darkblue
borderWidth	3

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 !

Panel

borderColor	#89A3C3
borderWidth	5
borderStyle	dashed

Based on the arc42 Template the

Wiki Link

page	projectdoc.volume.swad.title

for the HTML Sanity Checker

has been created.

Content Marker

hide	true

Transclusion

document	PDAC1:arc42 10th Anniversary Promotion
ids	Content

Section

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

Panel

borderColor	#192E59
titleColor	#192E59
titleBGColor	#89A3C3
title	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.

Section

title	Create by Wizard

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

Note Box

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.

Panel

title	Create the SWAD

Image RemovedImage Added

Panel

title	Create other Documents

Image Removed Image Added The example shows two of more than 40 blueprints.

Section

title	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:

Panel

title	Blackbox Document in Editor

Section

Column
Image RemovedImage Added

Column
Image RemovedImage Added

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.

Panel

title	Blackbox Document in View

The Blackbox in View Mode Image RemovedImage Added

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.

Section

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

Info Box

Transclusion of page fragments is usually slow. Therefore the

Wiki Link

page	projectdoc.volume.swad.title

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.

Section

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

Section

Column

width	50%

Panel

titleColor	white
titleBGColor	orange
title	1. Install the projectdoc Toolbox

Install the projectdoc Toolbox for Confluence now via

Column

width	50%

Panel

titleColor	white
titleBGColor	orange
title	2. Install Core Doctypes

Install the Core doctypes add-on now and for free via

Section

Column

width	50%

Panel

titleColor	white
titleBGColor	orange
title	3. Install Doctypes for Development

Install the projectdoc add-on for software development now and for free via

Column

width	50%

Panel

titleColor	white
titleBGColor	orange
title	4. Install Add-on for arc42

Install the arc42 Template for projectdoc now and for free via

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.

Section

title	What is projectdoc for Confluence?

Content Marker

id	why-should-i-care

Panel

borderColor	darkgreen
bgColor	lightgreen
titleColor	white
borderWidth	3
titleBGColor	darkgreen
borderStyle	solid
title	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

the organisation of documents
- spaces define homepages for types of documents
- spaces connect with other spaces
the individual document types
- document types define properties and sections
- automatic linking enhances navigability

The team can still benefit from the lightweight approach by using a wiki, and combine them with structures the team agrees upon.

Section

Column

Panel

borderColor	darkred
bgColor	lightred
titleColor	white
borderWidth	3
titleBGColor	darkred
borderStyle	solid
title	If you have 2 minutes ...

Watch our video introduction!

Column

Panel

borderColor	darkorange
bgColor	lightred
titleColor	white
borderWidth	3
titleBGColor	darkorange
borderStyle	solid
title	If you have some more minutes ...

Read the projectdoc Introduction!

Column

Panel

borderColor	darkgreen
bgColor	lightred
titleColor	white
borderWidth	3
titleBGColor	darkgreen
borderStyle	solid
title	Get started now?

Get started with projectdoc for Confluence!

Panel

borderColor	#342D7E
titleColor	white
titleBGColor	#342D7E
title	Volumes

Content Marker

css	projectdoc-homepage-panel-swdev
id	volumes-swdev

Wiki Link
empty-handling plain-text
page projectdoc.volume.vision-statement.title
Wiki Link
empty-handling plain-text
page projectdoc.volume.architecture-vision.title
Wiki Link
empty-handling plain-text
page projectdoc.volume.swao.title
Wiki Link
empty-handling plain-text
page projectdoc.volume.swad.title
Wiki Link
empty-handling plain-text
page projectdoc.volume.performance-management.title
Wiki Link
empty-handling plain-text
page projectdoc.volume.security-management.title
Wiki Link
empty-handling plain-text
page projectdoc.volume.test-management.title
Wiki Link
empty-handling plain-text
page projectdoc.volume.usability-management.title

Content Marker

css	projectdoc-homepage-panel-swdev
id	analysis-swdev

Panel

borderColor	#342D7E
bgColor	#F0F8FF
titleColor	white
titleBGColor	#342D7E
title	Analysis

Wiki Link
page projectdoc.content.vision-statements.home.title
Wiki Link
page projectdoc.content.features.home.title
Wiki Link
page projectdoc.content.out-items.home.title
Wiki Link
page projectdoc.content.user-characters.home.title
Wiki Link
page projectdoc.content.requirements.home.title
Wiki Link
page projectdoc.content.project-constraints.home.title
Wiki Link
page projectdoc.content.quality-targets.home.title
Wiki Link
page projectdoc.content.quality-scenarios.home.title

Content Marker

css	projectdoc-homepage-panel-swdev
id	design-swdev

Panel

borderColor	#342D7E
bgColor	#F0F8FF
titleColor	white
titleBGColor	#342D7E
title	Design

Wiki Link
page projectdoc.content.components.home.title
Wiki Link
page projectdoc.content.views.home.title
Wiki Link
page projectdoc.content.use-cases.home.title
Wiki Link
page projectdoc.content.architecture-aspects.home.title
Wiki Link
page projectdoc.content.architecture-decisions.home.title
Wiki Link
page projectdoc.content.technical-deptsdebts.home.title

Content Marker

css	projectdoc-homepage-panel-swdev
id	implementation-swdev

Panel

borderColor	#342D7E
bgColor	#F0F8FF
titleColor	white
titleBGColor	#342D7E
title	Implementation

API Documentation
Product Codes
Wiki Link
page projectdoc.content.properties.home.title
Reports
Releases / Build Metadata
Changes

Content Marker

css	projectdoc-homepage-panel-swdev
id	test-swdev

Panel

borderColor	#342D7E
bgColor	#F0F8FF
titleColor	white
titleBGColor	#342D7E
title	Test

Unit Tests
Integration Tests
Performance Tests
Security Tests
Acceptance Tests
Usability Tests

Column

width	20%

Content Marker

css	projectdoc-homepage-panel-swdev
id	swdev-deployment

Panel

borderColor	#342D7E
bgColor	#F0F8FF
titleColor	white
titleBGColor	#342D7E
title	Deployment

Wiki Link
page projectdoc.content.artifacts.home.title
Wiki Link
page projectdoc.content.environments.home.title
Wiki Link
page projectdoc.content.nodes.home.title

Space shortcuts

Child pages

Versions Compared

Old Version 4

New Version 5

Key

The Problem

The Solution