3 ms·

An alternative is to use an embedded diagramming syntax like dot or mermaid such that the diagrams are described as version controlled text and optionally rende

An alternative is to use an embedded diagramming syntax like dot or mermaid such that the diagrams are described as version controlled text and optionally rendered inline by e.g. VSCode. Cleaner than a litter of side car images in which it may be unclear what changed. See Markdown Preview Enhanced: https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced https://marketplace.visualstudio.com/items?itemName=shd101wy... Or add Mermaid to the built-in markdown preview: https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid https://marketplace.visualstudio.com/items?itemName=bierner.... You can also edit and enjoy these markdown pages with diagrams on Mac, iPad, iPhone: https://www.mweb.im/ https://www.mweb.im/ Lastly, if anyone is not sure what to diagram for readers of architecture.md, consider the C4 model: https://c4model.com/ https://c4model.com/

Gehinnn 6y ago
Text based diagrams definitively have their advantages over wysiwyg editors. However, sometimes the layout of a diagram also tells a story and I find it hard to express that with available text based diagram solutions. That's what I use draw.io aka diagrams.net for. I made an extension that helps to create markdown-embeddable/versionable draw.io diagrams in vscode: https://github.com/hediet/vscode-drawio https://github.com/hediet/vscode-drawio (there is also an IntelliJ extension) I have to admit that I sometimes struggle with pixel perfect layouts though and rearranging nodes is time intensive. However, most text based systems don't have a nice github integration and rely on manual export, which you can avoid when you diagram is not a plain text file but a rich diagram editor.