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.
Documenting concepts and software architecture as diagrams using code offers great benefit over heavier solutions. Having documentation and diagrams treated as code and checked-in into version control increases transparency, collaboration as well as productivity. The textual representation of diagrams is easy to write and read. Generation of graphical representations as SVG or PNG images is also easy with the associated tools.
We make heavy use of PlantUML combined with Asciidoc and tools like AsciiDoctor Diagram to include and inline PlantUML diagrams into documentations. The latter allows a variety of other diagram formats which can be easily mixed and matched.