AJR/TechradarDev
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: streamline formatting and proofreading

Browse Source
This commit is contained in:
Stefan Rotsch
2023-10-16 12:22:46 +02:00
committed by Stefan Rotsch
parent 2c541dfbea
commit 94ac286c34
43 changed files with 177 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
radar/2023-09-01/diagrams-as-code.md
View File

@@ -5,14 +5,11 @@ quadrant: methods-and-patterns
tags: [architecture, quality assurance, documentation]
---
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.
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 make heavy use of [PlantUML](/tools/plant-uml.html) combined with [Asciidoc](/tools/asciidoc.html) and tools like [AsciiDoctor Diagram](https://asciidoctor.org/docs/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.
We extensively use [PlantUML](/tools/plant-uml.html) in combination with [Asciidoc](/tools/asciidoc.html) and tools like [AsciiDoctor Diagram](https://asciidoctor.org/docs/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 are:
- [Mermaid](https://mermaid.js.org/) which is a JavaScript based diagramming tool that is natively supported by many common tools (e.g. Github, Gitlab, Gitea, Notion, etc. )
- [D2](https://d2lang.com/) is a diagram scripting language with a focus on readability providing a CLI and a Go library to programmatically create diagrams
- [Structurizr](https://structurizr.com/) brings his own DSL to create software architecture models based on the [C4 model](https://c4model.com/) and a CLI to export to formats like PlantUML, Mermaid, D2 and others.
Other tools worth mentioning include:
- [Mermaid](https://mermaid.js.org/), a JavaScript-based diagramming tool natively supported by many common tools (e.g., GitHub, GitLab, Gitea, Notion, etc.).
- [D2](https://d2lang.com/), a diagram scripting language that focuses on readability and provides a CLI and a Go library for programmatically creating diagrams.
- [Structurizr](https://structurizr.com/), which brings its own DSL for creating software architecture models based on the [C4 model](https://c4model.com/) and a CLI for exporting to formats like PlantUML, Mermaid, D2, and others.