- Created by Anton Kronseder, last modified by Robert Reiner on 22. Aug 2018
An example of an software architecture documentation based on the arc42 Template on Confluence 5 with projectdoc and the projectdoc Add-on for arc42.
-
Page:
-
Page:
-
Page:
-
Page:
- Resources
- Quotes
-
-
-
-
-
-
-
Organizations11. Oct 2018 • created by Robert Reiner
-
Persons11. Oct 2018 • created by Robert Reiner
-
Stakeholders11. Oct 2018 • created by Robert Reiner
-
Resources11. Oct 2018 • created by Robert Reiner
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.
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.
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:
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.
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!
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?
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.
Watch our video introduction!
Read the projectdoc Introduction!
- Vision Statement
- Architecture Vision
- Software Architecture Overview
- Software Architecture Documentation
- Performance Management
- Security Management
- Test Management
- Usability Management
- Vision Statements
- Features
- Out Items
- User Characters
- Requirements
- Project Constraints
- Quality Targets
- Quality Scenarios
- API Documentation
- Product Codes
- Properties
- Reports
- Releases / Build Metadata
- Changes
- Unit Tests
- Integration Tests
- Performance Tests
- Security Tests
- Acceptance Tests
- Usability Tests