Mermaid for Diagrams

[smiths]

At the UML for scientific software talk the speaker mentioned mermaid as a tool for drawing diagrams in GitHub. In our recent discussion of the chunk relation by @NoahCardoso and @balacij they drew diagrams in draw.io. I think we should still use draw.io (or similar tools), but if we want to talk about a smaller example where a picture would help, mermaid could be a good choice. It can be used to draw diagrams automatically in GitHub by using the triple quotes with the mermaid language identifier. The following example is from a GitHub repo of examples.

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }

Loading

[balacij]

This looks like a great tool! In all honesty, I wouldn't mind completely switching from draw.io over to this, too. We should see how this is rendered in commits and PRs too -- a side-by-side of UML diagrams would be very helpful!!

It looks like it has a pretty large community, with an online editor and a large list of tools it can be integrated with.

[smiths]

Yes, I think there is reason for optimism that mermaid could be a handy tool for us. As we discussed in yesterday's meeting (#3791), @NoahCardoso is going to investigate how our previous drawing (in draw.io) for the chunk relationships look in mermaid.

The list of integrated tools includes mdBook. Maybe there will come a time when we can start drawing figures like our system context figure in mermaid. We don't really have design diagrams, but it would be great to generate those in the future. Although the research software community is slow to recognize the value of requirements, documentation of design seems to be gaining momentum. They are also big on tools, so if we had a tool they could use to do things the "right way", I think we would garner some interest. 😄