From 484c90acd65d69bf6681a5834ad545913e529375 Mon Sep 17 00:00:00 2001 From: Henry Vogt Date: Wed, 12 Jul 2023 17:24:03 +0200 Subject: [PATCH] docs: update Diagrams as Code Adding some mentionable tools for diagramming in code. --- radar/2023-09-01/diagrams-as-code.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 radar/2023-09-01/diagrams-as-code.md diff --git a/radar/2023-09-01/diagrams-as-code.md b/radar/2023-09-01/diagrams-as-code.md new file mode 100644 index 0000000..2a85857 --- /dev/null +++ b/radar/2023-09-01/diagrams-as-code.md @@ -0,0 +1,18 @@ +--- +title: "Diagrams as Code" +ring: adopt +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. + +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. + +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.