Dave Gaeddert Process

Diagrams for Documentation

Simple flowcharts and diagrams 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.

I used to draw these kinds of things in Concepts 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)

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.

core products
Copyright © 2021 Dropseed, LLC. All rights reserved.