I’ve used mermaid for documentation, through plugins for mkdocs and Sphinx. What’s great about it is that the diagrams are stored as readable source text in the documentation, which is easy to diff and modify along with the rest of the doc (search and replace when renaming a component etc).<p>That’s a huge benefit compared to storing rendered bitmaps, with a source file next to them. There’s much more friction involved in keeping those up to date, the changes don’t display usefully in PRs etc. They’re almost never up to date as a result.<p>Another thing mermaid lets you easily do is generate sequence diagrams from code such as testcases, because the format is so simple and line-driven.
The outpout can also be included in documentation as samples, and is guaranteed to be up-to-date.