80 lines
4.1 KiB
YAML
80 lines
4.1 KiB
YAML
uuid:
|
|
- value: 2d05cfa9-d5cf-41df-ba50-2c55b776f1f5
|
|
langcode:
|
|
- value: en
|
|
type:
|
|
- target_id: daily_email
|
|
target_type: node_type
|
|
target_uuid: 8bde1f2f-eef9-4f2d-ae9c-96921f8193d7
|
|
revision_timestamp:
|
|
- value: '2025-05-11T09:00:08+00:00'
|
|
revision_uid:
|
|
- target_type: user
|
|
target_uuid: b8966985-d4b2-42a7-a319-2e94ccfbb849
|
|
revision_log: { }
|
|
status:
|
|
- value: true
|
|
uid:
|
|
- target_type: user
|
|
target_uuid: b8966985-d4b2-42a7-a319-2e94ccfbb849
|
|
title:
|
|
- value: 'Mermaid - markdown for charts'
|
|
created:
|
|
- value: '2024-08-18T00:00:00+00:00'
|
|
changed:
|
|
- value: '2025-05-11T09:00:08+00:00'
|
|
promote:
|
|
- value: false
|
|
sticky:
|
|
- value: false
|
|
default_langcode:
|
|
- value: true
|
|
revision_translation_affected:
|
|
- value: true
|
|
path:
|
|
- alias: /daily/2024/08/18/mermaid-markdown-for-charts
|
|
langcode: en
|
|
body:
|
|
- value: |
|
|
<p><a href="/daily/2024/08/16/what-are-err--req-and-res">Whilst mentoring at the School of Code Hackathon</a>, 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.</p>
|
|
|
|
<p>We kept it simple by adding this to a README file, but I also mentioned <a href="/daily/2022/09/23/adrs-technical-design-documents">ADRs and technical decision documents</a> and how they can be written in Markdown and stored alongside the code in the same repository.</p>
|
|
|
|
<p>Another approach to documentation that I like is to create diagrams and flow charts.</p>
|
|
|
|
<p>I've used various tools to do this, but recently, I've started to use <a href="https://github.com/mermaid-js/mermaid">Mermaid</a>, which is a Markdown-like syntax to generate charts and diagrams.</p>
|
|
|
|
<h2 id="here%27s-the-thing">Here's the thing</h2>
|
|
|
|
<p>There are online tools to do this, but there's also <code>mmdc</code> command-line tool that generates diagrams locally.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2 id="want-an-example%3F">Want an example?</h2>
|
|
|
|
<p><a href="https://github.com/opdavies/build-configs/blob/f02fce7ff5b5cff202ec8b893a4b3c7e7c56f3c4/docs/diagram.mmd">Here's one I did for the Build Configs tool</a>, which I recently open-sourced, and that GitHub renders by default (you can click the 'Code' tab to see the code for the chart).</p>
|
|
|
|
|
|
format: full_html
|
|
processed: |
|
|
<p><a href="http://default/daily/2024/08/16/what-are-err--req-and-res">Whilst mentoring at the School of Code Hackathon</a>, 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.</p>
|
|
|
|
<p>We kept it simple by adding this to a README file, but I also mentioned <a href="http://default/daily/2022/09/23/adrs-technical-design-documents">ADRs and technical decision documents</a> and how they can be written in Markdown and stored alongside the code in the same repository.</p>
|
|
|
|
<p>Another approach to documentation that I like is to create diagrams and flow charts.</p>
|
|
|
|
<p>I've used various tools to do this, but recently, I've started to use <a href="https://github.com/mermaid-js/mermaid">Mermaid</a>, which is a Markdown-like syntax to generate charts and diagrams.</p>
|
|
|
|
<h2 id="here%27s-the-thing">Here's the thing</h2>
|
|
|
|
<p>There are online tools to do this, but there's also <code>mmdc</code> command-line tool that generates diagrams locally.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2 id="want-an-example%3F">Want an example?</h2>
|
|
|
|
<p><a href="https://github.com/opdavies/build-configs/blob/f02fce7ff5b5cff202ec8b893a4b3c7e7c56f3c4/docs/diagram.mmd">Here's one I did for the Build Configs tool</a>, which I recently open-sourced, and that GitHub renders by default (you can click the 'Code' tab to see the code for the chart).</p>
|
|
|
|
|
|
summary: null
|
|
field_daily_email_cta: { }
|