Agree on tool and style for blueprint diagrams

[tiffany76]

As discussed in the 22 January SIG meeting:

• We should pick a tool that’s free and open.
  • OTel website supports Mermaid
  • Whimsical? - is it free?
• We should aim for consistency in Blueprint diagrams, and hopefully make them easy-ish to update.
• Reference architectures are meant to be snapshots in time (like a blog post), and they’ll come from end users, so we won’t be prescribing how those diagrams are created.
• The Blueprints template must specify how diagrams should be created.
  • The tool to use.
  • Any styling decisions for the sake of consistency.

[neil-the-nowledgable]

I'll help with this

[amineamanzou]

I did some research for a recent client where we were building documentation on Hugo/GitLab pages. Here are the open alternatives we looked at:

• Declarative Diagramming - MPL 2.0
• PlantUML - GPL
• Kroki - MIT
• Structurizr - Apache 2.0

In our case, for complex architecture diagrams we went with the classical DrawIO, and for highlighting concepts or illustrating ADRs we stuck with Mermaid.

That said, my heart goes to D2 (Declarative Diagramming). I really like the syntax and the aesthetic, which feels a bit more modern than standard Mermaid.

I'm also thinking about the localization criteria, if someone worked with localization contributors. I don't know how much this can impact your choices.