kiBon Software Architecture Documentation

Scripts inside /scripts are meant to be run from /documentation

Prerequisites

Install Ruby Gems:

• Asciidoctor

• Asciidoctor-Diagrams

• Asciidoctor-PDF

• Asciidoctor-Lists

To install required gems use the bundle command

• Download the structurizr-cli, unzip and move it into ./bin/structurizr-cli

curl --show-error --location https://static.structurizr.com/download/structurizr-cli.zip | tar -xf - -C bin/structurizr-cli

Build

• Generate the diagrams from the structurizr workspace model

#!/bin/sh

./bin/structurizr-cli/structurizr.sh \
 export -w documentation/src/domain/kibon.dsl \
  -format plantuml/structurizr \
  -output documentation/out/meta/diagrams

Generate the software architecture documentation representations

Generate the documentation as HTML representation

#!/bin/sh

asciidoctor -b html5 \
 -r asciidoctor-diagram \
 -r asciidoctor-pdf \
 -a pdf-theme=basic \
 -a pdf-themesdir=documentation/resources/themes \
 -a pdf-fontsdir=documentation/resources/fonts \
 -D documentation/out \
 documentation/kibon-system.adoc

Generate the documentation as PDF representation

#!/bin/sh

asciidoctor -b pdf \
 -r asciidoctor-diagram \
 -r asciidoctor-pdf \
 -a pdf-theme=basic \
 -a pdf-themesdir=documentation/resources/themes \
 -a pdf-fontsdir=documentation/resources/fonts \
 -D documentation/out \
 documentation/kibon-system.adoc

Create new requirement

1. Create a new numbered requirement under documentation/src/requirements

2. Use the following attributes to convey the necessary info about the requirement

   Parameters

   Name	Description	Required?
   :link:	Used to define the chapter link for xrefs	✓
   :title:	The requirement title used additionally for the link text of any xrefs to this requirement	✓
   :description:	A short description of the requirement, needs to be in a format that can be included using the include:…​[] syntax	✓
   :diagram:	File path to any potential diagram, needs to be in a format that can be included using the include:…​[] syntax	❌
   :diagramTitle:	The title of the diagram	(✓) only needed if :diagram: is defined
   :table:	File path to any potential table, needs to be in a format that can be included using the include:…​[] syntax	❌
   :tableTitle:	The title of the table	(✓) only needed if :table: is defined

3. To include the requirement in the document use

   include::requirements/<newRequirement>.adoc[]
   include::{templates}/requirement.adoc[]

Create new quality scenario

1. Create a new numbered quality scenario under documentation/src/qualities

2. Use the following attributes to convey the necessary info about the quality scenario

   Parameters

   Name	Description	Required?
   :title:	The requirement title used additionally for the link text of any xrefs to this requirement	✓
   :scenarioId:	The id of the scenario it is used to create a xref with quality<scenarioId>	✓
   :scenarioTitle:	The title of the scenario	✓
   :scenario:	The description of the scenario	✓
   :attributeQuality:	The quality attribute of this scenario	✓
   :attributeConcern:	The concerns of the attribute	✓
   :stimulus:	The stimulus triggering the scenario	✓
   :stimulusSource:	The actor triggering the stimulus	✓
   :environment:	The conditions needed for the scenario	✓
   :artifact:	The system artifact affected by the scenario	✓
   :response:	The response/output of the system to the scenario	✓
   :responseMeasure:	The measurment of system response to the given scenario	✓

3. To include the requirement in the document use

include::qualities/<newQualityScenario>.adoc[]
include::{templates}/qualityScenario.adoc[]

References

• Structurizr DSL Language Reference

• arc42 to get the structure for the software architecture documentation

• C4 Model an "abstraction-first" approach to diagramming software architecture, based upon abstractions that reflect how software architects and developers think about and build software.

• Structurizr DSL to describe the C4 Model of the software system

• Structurizr CLI a command line utility for Structurizr to export the PlantUML diagrams from the C4 Model described in the Structurizr DSL

• AsciiDoc as format to write the software architecture documentation

• Asciidoctor to generate the representations of the software architecture documentation written in asciidoc

---