From 98128530cf46daa5506062ec8f3458f992de2818 Mon Sep 17 00:00:00 2001 From: Oliver Davies Date: Mon, 19 Aug 2024 22:22:19 +0100 Subject: [PATCH] Add daily email for 2024-08-18 Mermaid - markdown for charts --- source/_daily_emails/2024-08-18.md | 35 ++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 source/_daily_emails/2024-08-18.md diff --git a/source/_daily_emails/2024-08-18.md b/source/_daily_emails/2024-08-18.md new file mode 100644 index 00000000..3e8e7f2e --- /dev/null +++ b/source/_daily_emails/2024-08-18.md @@ -0,0 +1,35 @@ +--- +title: Mermaid - markdown for charts +date: 2024-08-18 +permalink: daily/2024/08/18/mermaid-markdown-for-charts +tags: + - software-development + - documentation +cta: ~ +snippet: | + Mermaid is a nice way to generate and store diagrams within your projects. +--- + +[Whilst mentoring at the School of Code Hackathon][0], something the team and I discussed was documentation and documenting any decisions we made about the approaches they were taking, the techologies to use, etc. + +We kept it simple by adding this to a README file, but I also mentioned [ADRs and technical decision documents][1] and how they can be written in Markdown and stored alongside the code in the same repository. + +Another approach to documentation that I like is to create diagrams and flow charts. + +I've used various tools to do this, but recently, I've started to use [Mermaid][2], which is a Markdown-like syntax to generate charts and diagrams. + + +## Here's the thing + +There are online tools to do this, but there's also `mmdc` command-line tool that generates diagrams locally. + +This means that I can easily generate diagrams and store in the codebase too, and have them version-controlled so I can see the history as they evolve during the project. + +## Want an example? + +[Here's one I did for the Build Configs tool][3], which I recently open-sourced, and that GitHub renders by default (you can click the 'Code' tab to see the code for the chart). + +[0]: {{site.url}}/daily/2024/08/16/what-are-err--req-and-res +[1]: {{site.url}}/archive/2022/09/23/adrs-technical-design-documents +[2]: https://github.com/mermaid-js/mermaid +[3]: https://github.com/opdavies/build-configs/blob/f02fce7ff5b5cff202ec8b893a4b3c7e7c56f3c4/docs/diagram.mmd