TechradarDev/radar/2023-11-01/diagrams-as-code.md

title, ring, quadrant, tags

title	ring	quadrant	tags
Diagrams as Code	adopt	methods-and-patterns	architecture quality assurance documentation

Documenting concepts and software architecture as diagrams using code offers significant benefits over heavier solutions. Treating documentation and diagrams as code and checking them into version control increases transparency, collaboration, and productivity. The textual representation of diagrams is easy to write and read, and generating graphical representations as SVG or PNG images is also straightforward with the associated tools.

We extensively use PlantUML in combination with Asciidoc and tools like AsciiDoctor Diagram to include and inline PlantUML diagrams in our documentation. The latter allows for a variety of other diagram formats, which can be easily mixed and matched.

Other tools worth mentioning include:

• Mermaid, a JavaScript-based diagramming tool natively supported by many common tools (e.g., GitHub, GitLab, Gitea, Notion, etc.).
• D2, a diagram scripting language that focuses on readability and provides a CLI and a Go library for programmatically creating diagrams.
• Structurizr, which brings its own DSL for creating software architecture models based on the C4 model and a CLI for exporting to formats like PlantUML, Mermaid, D2, and others.