Documentation as Code Tech Stack

This page contains all the modern tools, languages and frameworks, platforms and techniques you need to know to treat documentation like code.

If documentation as code tool or a diagram as code tool is missing here, please contact me.

Table of Contents

Tools
Languages & Frameworks
Techniques
Platforms

Tools

Asciidoctor

Asciidoctor is an open source text processor and publishing tool that converts plain text into various output formats, such as HTML, PDF, EPUB, and more. It is designed to be a modern implementation of the AsciiDoc markup language, which was created as an alternative to Markdown.

docToolchain

Doctoolchain is a toolchain used to build, test, and publish software documentation.

It is a set of open-source tools that automates the documentation process, including building documentation from source code, generating HTML, PDF, and other formats, and publishing to various platforms. It aims to simplify the documentation process and reduce the time and effort required to create high-quality documentation.

Doctoolchain is popular among developers, technical writers, and documentation teams who want to streamline their documentation workflow.

adr-tools

A command-line tool for working with a log of Architecture Decision Records (ADRs).

Context Mapper

The context mapper is a tool used in domain-driven design (DDD) to identify and visualize the different contexts within a complex business domain. It helps to break down a large domain into smaller, more manageable parts and to identify the relationships and boundaries between them.

The context mapper can be used to create a context map, which is a diagram that shows the different contexts and their relationships, and can help teams to better understand the domain and design more effective software systems.

Contexture

Typically, a bounded context canvas is created on physical paper using post-ITs, while the digital versions are usually just a reflection of the physical representation, for example using Miro. This means that the captured information is presented as free text on virtual post-ITs and isn't stored in a structured way. This prevents further data processing and visualization of the information.

This is where Contexture comes into play, the:

stores information about a BoundedContextCanvas in a structured way instead of just using free text on (virtual) Post-ITs,
allows explicit connections between different bounded contexts,
supports updating and versioning of the information over time,
allows to export and visualize the information from the application,
and helps people to input data for a BCC easier

Languages & Frameworks

AsciiDoc

AsciiDoc is a lightweight markup language used to write technical documents, user manuals, and other forms of technical documentation. It is based on the ASCII text format and uses plain text files to create structured documents that can be easily converted to HTML, PDF, and other formats. AsciiDoc provides a simple syntax for formatting text, creating tables, inserting images, and other advanced document elements. It is also highly extensible, allowing developers to create their own macros and plugins to add additional functionality to their documents.

PlantUML

PlantUML is an open-source tool that allows developers, analysts, and other users to create UML (Unified Modeling Language) diagrams quickly and easily. It uses simple text-based syntax to define UML diagrams, making it easy to create diagrams without needing to use a graphical tool. PlantUML supports a wide range of UML diagrams, including class diagrams, activity diagrams, use case diagrams, sequence diagrams, and more. It can also generate output in a variety of formats, including PNG, SVG, and PDF.

Mermaid

Mermaid is a JavaScript based diagramming and charting tool that renders Marksdown-inspired text definitions to create and modify diagrams dynamically.

D2 Lang

D2 is a scripting language for diagrams that converts text into diagrams. It stands for Declarative Diagramming. Declarative, that is, you describe what you want to represent in a diagram, and it generates the image.

Graphviz

Graphviz is open source graph visualization software. Graph visualization is a way of representing structural information as diagrams of abstract graphs and networks. It has important applications in networking, bioinformatics, software engineering, database and web design, machine learning, and in visual interfaces for other technical domains.

Structurizr DSL

The Structurizr DSL is a domain-specific language (DSL) for describing software architecture models using code. It allows developers to define system components, their relationships, and their interactions using a concise and expressive syntax, which can be easily version controlled and shared with other team members. The DSL is designed to be easy to read and understand, and it supports a variety of output formats, including diagrams, tables, and JSON. The Structurizr DSL is part of the Structurizr toolset, which is a collection of tools and libraries that help software teams create and maintain architecture models.

c4Viz

Diagrams

Diagrams lets you draw the cloud system architecture in Python code.

It was born for prototyping a new system architecture without any design tools. You can also describe or visualize the existing system architecture as well.

Ilograph

Ilograph is an interactive diagramming tool for documenting complex systems. It's designed for engineers of all types who want to create documentation that is more detailed, comprehensive, and understandable than is possible with traditional static diagrams and text.

Goa Model

Model provides a way to describe software architecture models using diagrams as code. This approach provides many benefit over the use of graphical tools, in particular:

Built-in history via source control versioning: Each change to the software architecture model results in a commit making it natural to implement Architectural Decision Records.
Simple and consistent reuse of shared architecture components: The code of shared architecture components can be imported by other software systems. Apart from the obvious time saving a major advantage is ensuring that all references are automatically kept up-to-date as the shared architecture component evolves. The shared architecture component code can be versioned using traditional source code versioning techniques as well.
Consistent notation and visual styles: The same mechanism used to import shared architecture diagram can also be used to import shared style definitions.
Ability to control drift between reality and diagrams: Static code analysis allows writing tools that compare the software models with actual code to detect discrepencies (this repo does not provide such a tool at this time).

EventCatalog

Techniques

arc42

arc42 is a template for creating software architecture documentation. It provides a structure and guidelines for documenting software architecture.

Platforms

Kroki

Kroki provides a unified API with support for creating diagrams from different textual descriptions.

Terrastruct

Terrastruct is a diagramming tool specialized for software architecture and other complex systems such as the domain your business operates in.

What makes this different from other diagramming tools is that it gives you a multidimensional view of your system. Define layers to go up and down the stack, scenarios to explore hypotheticals or error cases, and use frames for defining sequences.

Structurizr Cloud Service

Structurizr Cloud allows you to get started with Structurizr quickly, without the need to host and update software on your own servers.

IcePanel

Icepanel is a collaborative architecture modeling tool designed for software teams to plan, visualize, and communicate their system designs effectively. It simplifies the process of creating C4 models, making it easier to represent software architecture at different levels of detail. With an intuitive interface, Icepanel enables real-time collaboration, helping teams align on architectural decisions and document their designs effortlessly. Its focus on simplicity and team collaboration makes it ideal for agile workflows and modern DevOps practices. Icepanel is a powerful solution for ensuring clear, consistent communication across technical and non-technical stakeholders.

Docusaurus

Docusaurus is a modern, open-source framework for building documentation websites quickly and efficiently. Created by Meta (formerly Facebook), Docusaurus simplifies the process of creating well-organized, visually appealing, and performant static sites. It’s ideal for technical documentation, blogs, and project wikis.

Antora

Antora is a powerful, open-source static site generator specifically designed for creating documentation websites. It excels in handling multi-repository and multi-versioned documentation, making it a top choice for projects with complex documentation needs.

Antora uses Asciidoc as its primary markup language, providing a highly readable syntax for creating rich, structured content. Its modular architecture allows teams to organize documentation into separate repositories and manage multiple versions seamlessly. This makes Antora ideal for large-scale software projects where clear, consistent, and easily navigable documentation is crucial.