search

MetPX / sarracenia

https://MetPX.github.io/sarracenia
GNU General Public License v2.0
45 stars 22 forks source link

Replace Visio Diagrams #1240

Open petersilva opened 1 month ago

petersilva commented 1 month ago

The only non-text format used in the documentation is a handful of Visio diagrams. Some of those diagrams are exported to SVG format and then the svg is edited in a drawing program. these are all in the docs tree:


SSC-5CD2310S60% find . -name '*.vsdx'  -o -name '*.vsd'
./fr/Explication/Concepts/sr3_exemple_de_flux.vsdx
./fr/Explication/Concepts/amqp_notion_de_flux.vsdx
./Explanation/Concepts/e-ddsr-components.vsd
./Explanation/Concepts/sr3_flow_example.vsdx
./Explanation/Concepts/amqp_flow_concept.vsdx
SSC-5CD2310S60%

Perhaps they could be replaced with open source tech.

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams

MagikEh commented 1 month ago

I find the best 'pipeline' to making a diagram in mermaid is to doodle it out in paint/on paper to get it out of my head and then organize it in a way that's easily represented by mermaid. From there I like to use the https://mermaid.live/ editor to get realtime updates of the structure I'm typing in (don't have to hit preview to see little changes), and finally It's just a matter of pasting it into the docs.

flowchart LR

    FIND[Find a Visio diagram]
    DOODLE(Doodle it out)
    THINK{Can it be mermaidified easily?}
    MERM((Use mermaid.live to draft it))
    GIT[Dump graph into git]

    FIND --> DOODLE
    DOODLE ---> THINK
    THINK -->|Non| DOODLE
    THINK -->|Oui| MERM
    MERM --> GIT

I will note though, there are things in the mermaid.live editor that potentially aren't in github/gitlab, as the former use a markdown interpreter that's based off usually not the latest version of mermaid.