Conceptual design of implementing a Software Architecture Document with Atlassian Confluence

Overview

This blog post showcases a conceptual design for implementing a Software Architecture Document (SAD) in a Atlassian Confluence Wiki.

Purpose

Share the design concept to a broad audience by publishing online.

Scope

Defines the initial steps for creating Atlassian Confluence (will be referenced as Confluence from here forward) wiki pages aligned with the SAD example provided by the Software Engineering Institute (SEI).

Background

I was working on a project which was getting into a documentation problem.   I wanted to know the common practices in industry and started researching documentation practices for software architecture and systems.  The research led to the ISO/IEC 42010 standard, SEI’s contribution to the topic and the related Documenting Software Architectures: Views and Beyond book on the same topic.

In the specific project I was working on, the direction was to use Confluence for documentation.  While I had been regularly publishing to the wiki and benefiting from using the Macro and Template features, I wanted to dive  deeper into what Confluence had to offer to understand how the concepts of the SAD can be applied to the wiki to provide a documentation solution requiring a reasonable effort to maintain and scale.

Design Description

Overview

The flow is for the publishers of the documentation to start with the SAD Microsoft Word template, import the template into Confluence, create Confluence Template Pages, and add sections to Confluence using Confluence Templates as the architecture changes over time.

Implementation

The remaining parts of this section describes the implementation in more detail.

Initialization and Addition of pages

The intended flow is as follows:

  1. Publishers download the SAD Microsoft Word template,
  2. Publishers edit SAD template and save
  3. Publishers import SAD document into wiki
  4. Publishers add Viewpoint Definitions, Views and View Packets using Templates.

Template Design and Macro Usage

This section provides a structural view of the wiki modules used in the design.

The UML Class Diagram below shows the templates and macros used in this design.

Class Diagram
Class Diagram

 

The UML Object Diagram below shows the pages that would exist for a scenario where there are two Views, each View having two View Packets.

Object Diagram
Object Diagram

Leave a Reply

Your email address will not be published. Required fields are marked *