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