Documentation

In addition to static and dynamic diagrams, Structurizr also provides support for lightweight, supplementary technical documentation created using Markdown or AsciiDoc. In the same way that the C4 model provides a simple structure for diagrams, the documentation support in Structurizr is based upon the "software guidebook" from Simon Brown's Software Architecture for Developers: Volume 2 book.

The documentation is essentially a collection of Markdown or AsciiDoc documents, one per section, which are rendered in the web browser. This content is uploaded in a workspace along with the software architecture model. In addition, Structurizr diagrams from the same workspace can be embedded.

A screenshot of the documentation feature

Lightweight structured supplementary documentation

The goal of the documentation feature in Structurizr is to provide a way to create lightweight structured, supplementary technical documentation for a software system, to describe the things you can't get from the code. As a way to introduce some structure, the documentation is broken up into the following sections.

  1. Context
  2. Functional Overview
  3. Quality Attributes
  4. Constraints
  5. Principles
  6. Software Architecture
  7. Code
  8. Data
  9. Infrastructure Architecture
  10. Deployment
  11. Development Environment
  12. Operation and Support
  13. Usage
  14. Decision Log

A screenshot of the documentation feature

Why?

Exploring the code is great fun but ultimately it takes time, which we often don't have. Since the code doesn't tell the whole story, some supplementary documentation can be very useful, especially if you're handing over the software to somebody else or people are leaving and joining the team on a regular basis. You can think about this supplementary documentation as a guidebook, which should give people enough information to get started and help them accelerate the exploration process.

Getting started

You can find some documentation and examples on both the Structurizr for Java and Structurizr for .NET GitHub repositories.

Markdown

The markdown-it library is used to render the documentation content in the web browser. This is a comprehensive implementation of the Markdown format, providing support for all of the basic elements such as paragraphs, lists, images, etc.

Embedding software architecture diagrams

In addition to the usual Markdown syntax, you can embed diagrams from the workspace into your documentation using the following syntax.

![](embed:MyDiagramKey)

This will embed the diagram with the key MyDiagramKey into the documentation page.

Images

Images can be included using the regular Markdown syntax. For this to work, the image files must be hosted externally (e.g. on your own web server) or uploaded with your workspace.

UML diagrams

You can also use services such as yUML to include UML diagrams. For example:

![A simple UML class diagram]( http://yuml.me/diagram/nofunky/class/[Class A]->[Class B] )

AsciiDoc

The asciidoctor.js library is used to render the documentation content in the web browser, supporting all of the basic elements such as paragraphs, lists, images, etc.

Embedding software architecture diagrams

In addition to the usual AsciiDoc syntax, you can embed diagrams from the workspace into your documentation using the following syntax.

image::embed:MyDiagramKey[]

This will embed the diagram with the key MyDiagramKey into the documentation page.

Images

Images can be included using the regular AsciiDoc syntax. For this to work, the image files must be hosted externally (e.g. on your own web server) or uploaded with your workspace.