🟢 Document various declarative, text-based diagram tools we use

[ryanhofdotgov]

PlantUML, mermaid, edotor, etc.:
https://gsa-tts.slack.com/archives/C02CD5VUQ/p1601310859025700

[Sgtpluck]

Initial ask:

I want to include a simple diagram in a Markdown file in a Github repo just for project documentation purposes. I’ve used Google Drawings and I could make a PNG export and put it in the repo and include it. But I’d rather have something where the source of the diagram could go in the repo with the document.
Is there something that people have used for diagrams that they would suggest? Is there some other diagram software that is common enough that its native file format would be reasonable to include in a repo? Or just include the PNG and put a link somewhere to the original Google drawing?

Add some context around what the tools are used for, and possible use cases

[adunkman]

Mermaid just got inline rendering support from GitHub

[mogul]

I have used the the C4 Model for representing system architecture, which the PlantUML standard library supports well, to implement diagrams-as-code. (Following links from the C4 site to text-based tooling for authoring C4 diagrams is what led me to start using PlantUML in the first place.) You can see examples of C4 PlantUML in action for data.gov.

This has also been incorporated into the rails-template to give people a head start in adopting these tools. (Note, however, that there's no GitHub Action to regenerate the rendered diagrams when source changes; that is still handled by hand.)

You can also use PlantUML for sequence diagrams like this generic SCM/CI/CD diagram, or many other diagram types, not just those specified in UML.