Documentation with Markdown or AsciiDoc

Because the code doesn't tell the whole story, Structurizr also provides support for lightweight supplementary technical documentation, based upon a number of popular templates. You can also create your own custom template.

The documentation is 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, which makes it easy to embed diagrams from that workspace.

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.

Examples

Here are some example documentation templates.

Software guidebook

Software guidebook

The "software guidebook" from Simon Brown's Software Architecture for Developers: Volume 2 book.

GitHub Java C# Markdown AsciiDoc

Software guidebook

arc42

The arc42 template, by Dr. Gernot Starke and Dr. Peter Hruschka.

GitHub Java C# Markdown AsciiDoc

Software guidebook

Viewpoints and Perspectives

The Viewpoints and Perspectives template, from Software Systems Architecture by Nick Rozanski and Eoin Woods.

GitHub Java C# Markdown AsciiDoc