DEV Community

Cover image for Scaling Diagram Documentation
Sibelius Seraphini for Woovi

Posted on

4

Scaling Diagram Documentation

At Woovi we are adding more and more documentation for all domains of product.
We have documentation for very specific implementation of the codebase to the higher level, to the high level of architecture and data modelling.
We are using different types of diagrams to describe some aspect of a domain, like state machines, sequence diagrams and flowchart.

Unstructured diagram workflow

Each developer start adding their diagrams using their favorite tool, like excalidraw, mermaid or even Figma.
It is great to have flexibility to build any diagram you want, but this flexibility is also hard to scale.

Problems with image-based diagram tools

Excalidraw and Figma provides a lot of flexibility to create your diagrams.
The workflow to add an excalidraw/figma diagram to our documentation is:

  • Create the diagram using excalidraw/figma
  • export an image of the diagram
  • add the image to the documentation

The problem with this approach is that we can't ensure consistency across diagrams, it is like if every developer writes their own CSS.
Another drawback of this approach is that it is not easy to edit the diagram. If you don't have the excalidraw/figma source, you would need to recreate the whole diagram by hand.
Also, you can't search on text inside diagrams, as they are images.

Text-based diagram tool

To solve all these problems, we investigate some text-based diagrams, and the one that fits better in our workflow is mermaid.
Mermaid renders Markdown-inspired text definitions to create and modify diagrams dynamically.
All our documentation is already in Markdown, so writing a diagram in mermaid is easy to learn.
Mermaid render on GitHub issues, so we can easily move diagrams from issues to our documentation.
Mermaid provides a Live Editor
You can easily copy, paste, edit and search diagrams.
We also solve the consistency problem, and we avoid recreating existing diagrams types.
It also works with ChatGPT and Show Me plugin.

In Conclusion

We still use Excalidraw and other image based diagrams for drafts and discussions, but when everything is decided, we move them to text-based mermaid to add to documentation.
As we grow, we are adding just a bit more of structure to make sure we enable can scale without moving slow.


Thanks to Eduardo from Woovi that come up with this proposal.


Woovi
Woovi is a Startup that enables shoppers to pay as they like. To make this possible, Woovi provides instant payment solutions for merchants to accept orders.

If you want to work with us, we are hiring!


Photo by Nsey Benajah on Unsplash

Billboard image

Use Playwright to test. Use Playwright to monitor.

Join Vercel, CrowdStrike, and thousands of other teams that run end-to-end monitors on Checkly's programmable monitoring platform.

Get started now!

Top comments (0)

Sentry image

See why 4M developers consider Sentry, “not bad.”

Fixing code doesn’t have to be the worst part of your day. Learn how Sentry can help.

Learn more

👋 Kindness is contagious

Discover a treasure trove of wisdom within this insightful piece, highly respected in the nurturing DEV Community enviroment. Developers, whether novice or expert, are encouraged to participate and add to our shared knowledge basin.

A simple "thank you" can illuminate someone's day. Express your appreciation in the comments section!

On DEV, sharing ideas smoothens our journey and strengthens our community ties. Learn something useful? Offering a quick thanks to the author is deeply appreciated.

Okay