DEV Community

Cover image for Diagrams for documentation
Dave Gaeddert for Dropseed

Posted on • Originally published at dropseed.io

Diagrams for documentation

Simple flowcharts or drawings are a good way to explain concepts without a ton of words.

Technical documentation is a lot more interesting (and helpful) when you mix in some visuals.

One of my favorite ways to do this is to use Excalidraw.
Excalidraw is an open-source whiteboard that strikes a balance between hand-drawn and professional.

  • No login required
  • Limited fonts and colors (a good thing!)
  • Arrows automatically connect to other elements
  • Works pretty well on iPad
  • Drawings can be saved and shared with a link

I used to draw these kinds of things on my iPad, but my handwriting sucks and there aren't very clean ways to save and revise drawings in the future, especially for someone besides myself. Figma is another option here, but for simple diagrams that often gives me too many options which pull me into "high-fidelity" mode and then I get stuck.

The limitations of Excalidraw are a feature, not a bug.

Here's an example that I used on dropseed/deps:

Excalidraw for documentation example

And here it is being used on the README:

dropseed/deps README with Excalidraw

The best part? There's a link to the drawing itself, commented out in the markdown:

<!-- Edit in Excalidraw: https://excalidraw.com/#json=6195990008692736,unm4UYeUzdmbXTk_xcvIdQ -->
![deps overview flowchart](https://user-images.githubusercontent.com/649496/111809843-675b1000-88a3-11eb-8b5c-d85d71cb5a25.png)
Enter fullscreen mode Exit fullscreen mode

Anybody can open that Excalidraw link (including me), edit the drawing and contribute a new version to the README. No complicated software or design tools, and limited choices in fonts, colors, and style.

Top comments (0)