Share the design concept to a broad audience by publishing online.
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).
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.
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.
The remaining parts of this section describes the implementation in more detail.
Initialization and Addition of pages
The intended flow is as follows:
- Publishers download the SAD Microsoft Word template,
- Publishers edit SAD template and save
- Publishers import SAD document into wiki
- 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.
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.