As a technical documentation writer, I am always looking for ways to relay information better and communicate that to our audiences. Oftentimes, that involves recognizing the role visual graphics can play in your documentation.
Despite a career in publishing and working as a technical writer, graphics have always been tough for me. I get the whole “a picture is worth a thousand words” thing, but creating useful and polished graphics has never been one of my strengths. I fret over details like making sure lines between objects are straight and have the same length and width. The more I worry, the more I fiddle with the graphic, the less happy I am.
Then I discovered Mermaid, a Javascript-based tool that automatically renders Markdown text definitions into diagrams and charts. Stoplight added support for Mermaid in 2021, but I never took the time to do more with it than test a few examples in the documentation.
That doesn’t mean there wasn’t a need for Mermaid in the Stoplight docs. For example, the documentation for Prism, Stoplight’s open-source mock server tool, contained a decision tree that was impossible to read. A developer created the tree using a collaboration tool, took a screenshot, then added it to a Markdown topic.
Here’s how the original diagram appeared in the Prism documentation…Yikes!
During a recent analytics review, I noticed that the HTTP Mocking topic gets a fair amount of traffic, so it seemed like a good time to tackle the image – and Mermaid. Read the HTTP Mocking topic to see the final result.
Where to Start?
My first stop was the Stoplight documentation. The simple examples are a good start, but I quickly needed more. I followed the Stoplight link to the excellent Mermaid documentation to learn how to create, connect, and customize nodes. These are the shapes that contain descriptive text. You can also add text to the connectors.
Once I had a few nodes in place, I attempted to break the rather complex decision tree into separate diagrams. I thought that would be easier for readers to digest. If nothing else, the smaller chunks helped me create the full diagram. Here’s an example of a small chunk:
Here’s the Mermaid syntax for the small diagram:
```
flowchart TB
1A[HTTP Request] --> 1B{Route exists?}
1B -->|No| 1C[404 problem+json]
1B -->|Yes| 1D{Is request valid?}
1D -->|Yes| 1E[Negotiate for valid request]
1D -->|No| 1F[Negotiate for invalid request]
classDef Orange fill:#f58442
classDef Red fill:#EE7968
class 1A,1B,1D,1E,1F Orange
class 1C Red
```
I planned to create two additional diagrams: one for negotiating a valid request and one for negotiating an invalid request. But after creating the smaller diagrams, I realized I would need to tie the three images together with a separate explanation. This might be more confusing than the larger diagram.
Luckily, I was able to easily combine the three diagrams using numbers to separate the nodes for each (1 for the HTTP request portion, 2 for negotiating valid requests, and 3 for negotiating invalid requests).
Mermaid Love
Mermaid’s flexibility made a seemingly daunting task relatively easy. I’d put off learning it because I assumed it would take weeks to learn. In reality, I created the new Prism diagram in a few hours.
Here are some of my favorite takeaways:
- I used a flowchart, but you can create pie charts, user journeys, class diagrams, and more.
- I love the options for creating different node shapes and connector types. I also love relegating the rendering of these to Mermaid.
- The guidance on creating classes saved me time as I created the diagram and will help with long-term maintenance.
- I didn’t find the Mermaid Live Editor until I finished the Prism decision tree, but it’s a great way to see examples and create your own diagram. You can copy Markdown from the site to paste it into a Stoplight Markdown file. You can even export your creation as a .png file.
- Stoplight readers will definitely see more diagrams in the future, thanks to Mermaid!
To learn more about how to add Mermaid to Stoplight for your own Workspace check it out here.
