I draw a lot of diagrams at work. What makes it kind of worse is that now a days I’m very cross-platform: while I still enjoy the power duo of OmniOutliner and OmniGraffle, I currently use Windows for work, and most of my after hours experimentation happens either on Windows or Linux. I might use MacOS a couple hours a week.

So, given I might need to either write a quick diagram down to explain something, or to add to source code documentation, or as a guide for myself, how do I do it?

I almost mostly want to optimize for fast diagramming tools that give me relatively good results while in the middle of brainstorming by doing. Nothing takes me out of flow faster than having to right click control l shift, now which part of the dialog box lets me control line thickness gain, etc.

Turns out I have different tools for different tasks, depending on how much I have to share the diagram or how big the diagram is going to be.

Remarkable

I bought my Remarkable in Febuary. For better or worse this is almost exactly an infinite paper notebook (or, suitcase full of folders of paper notebooks).

To counter the fact that there’s limited to no searching of notes on the Remarkable, I manually keep a separate notebook: “Changelog”, where I keep track of what I’ve done day to day and where past-me organized a thought.

For drawings that fit on about 8.5x11 pieces of paper the Remarkable is a great, lightweight, almost paper like experience. But its a little bit (and just a little bit, in my experience) better that paper in the following ways:

• I can copy/paste segments of drawing
• With selection comes rotation (if I’m running out of space sometimes turning the page to landscape mode gives me just enough space to finish it up)
• With selection comes scaling: that big circle takes up too much space Select and scale down.
• I can select and move some aspect of the drawing out of the way, or in a better place as the drawing evolves

The disadvantages is that my diagrams have to about fix on that 8.5x11 sheet of e-paper. The remarkable can zoom a page to 300% size, but I find I had to almost start it that way first and then pan around a lot, but this takes me out of the flow.

Sometimes though, simple one pager is all I need. I’ve loaded mine up with custom templates. Because it’s eInk the battery for me (an hour or two a day use, max) lasts a couple weeks.

Usually I keep the Remarkable for personal diagrams: diagramming out how I’m going to implement some feature, and half personal todo list. I also may use it as a brainstorming tool, or place to keep thoughts.

Given my usage patterns (maybe an hour of hard use a day), the battery is good for a week or two.

Remarkable -> computer based format

Email a page to myself to get it off the tablet, or connect it via usb-C to browse the local file system.

The Remarkable provides read-only sync, by way of apps, to MacOS, Windows, iOS and probably Android devices. But it doesn’t provide a write interface for anything but their hardware. So for my upcoming vacation I’ll have to debate - if I want to use the Remarkable at all, I’ll have to pack it, or do I just use my current notes as reference and make changes elsewhere?

Wipebook + pictures

I’ve sold at least two Wipebook notebooks. Imagine an 8.5x11 notebook, but instead of papers it’s whiteboard material. Use whiteboard markers or semi-permanent reusable markers and your work wipes off.

Almost an infinite notebook. I have diagrams in there that have lasted years, and pages where I’ve erased a diagram after a couple of days because I didn’t need it anymore.

Wipebook (or any physical format: paper, whiteboards, etc)-> computer based format

Different way la depending on the task, but both use Microsoft Lens

(Microsoft Lens was previously called Office Lens) Office Lens -> whiteboard, take a picture of it OR use a previously captured picture

You can export it as a plain ol’ photo or PDF, and something very interesting happens when you export hand drawn notes to Powerpoint format (of all things): you will be able to move the parts of the diagram about. That line you drew that technically needs to be somewhere else? It’a a vector art (or close enough), so just MOVE THAT LINE

It won’t convert these to computer absolutely straight boxes, nor will it convert that handwritten “ASAP” to text (it’s four shapes: your A shape, your “S” shape, etc etc)… but it’s potentially good enough for that presentation or software artifact.

OneNote

Micosoft OneNote is a fantastic notes repository.

Looking through my OneNote it’s 90% pictures of technical documents I put in there with Microsoft Lens, but it has four things going for it in the technical diagramming space:

1. Cross-platform nature (iOS, MacOS, Windows, Web)
2. Infinite canvas
3. Text can be easily placed at arbitrary points on the diagram
4. On my iPad and my stupid convertible Windows tablet/laptop, freehand drawing on the screen can be converted to shapes. Draw something approximately box like? Watch it turn into a vector box in front of your eyes.

Some shapes (hand draw arrows) don’t get picked up BUT can set your current tool to that shape and draw it

It’s likely very good from going from brainstormed draft -> polished thing. (but seems like no way to go from ink -> shape at a later date?)

I mostly draw in OneNote as a prototype for big drawings: is this important diagram (that I know will need lots of space) important / useful at all? Is it useful enough to (manually) convert it to some other Vector based format like Visio or Omnigraffle? Or is it fine as a personal reference?

OneNote is reasonably good on my iPad - haven’t tried it on an iPad Pro - but it’s really good on my old convertable laptop / tablet notebook. Tablet mode for quick drawing / sketching, then I unfold the tablet and there’s my keyboard for heavy typing.

For the most part I’m able to maintain flow while in OneNote, and not worry about the interface getting in the way of diagramming.

GraphViz

GraphViz does one thing and does it well: directed and undirected graphs from a textual format.

I’m really good at getting in the flow with GraphViz. I use it for anything from quick mindmaps to relatively complex architectural diagrams.

If you want directed or non-directed graphs, where you don’t want to worry about the exact layout of the nodes, but you care very much about the edges / relationships, this is my favorite tool. However, it only does this.

It’s portable nature is great too: I know of a Confluence plugin that converts Graphviz text to a rendered graph, and my Gatsby blog can render a graph fom a Graphviz code block.

There are some places wish had integration with Graphviz renderers. I recently had to send a digram to someone in Slack. I actually wrote out the GraphViz, rendered it in Visual Studio Code, exported to PNG and messaged my friend. Sometimes a picture is worth a thousand words.

and outlines

I’ve been experimenting with the idea that outlines and mindmaps may be two different presentations of the same resource (to use words from REST architecture). That they are the same object / concept, but different views on the same thing.

In the general I’ve had reasonably good luck with this: sometimes I’ll outline something, graph it, and then realize that this node in the graph doesn’t actually go with the other nodes around it. But it took a diagram for me to see that - an outline, for me, would have obscured that.

I have, and have deployed, a development version of a tool which helps translate (Markdown based) outlines to (GraphViz) diagrams. Markdown Mindmap Beta. (My fun React + Typescript + probably GraphQL + learning oddball parts of AWS project! Very early stage!)

PlantUML

PlantUML - same text description language -> rendered graphic idea as GraphViz, just with more output types. I am not great getting into the flow with PlantUML (larger language to learn). However, I’ve created very complex diagrams with PlantUML: sequence diagrams and Gantt charts mostly.

I really do like not needing to care where a node is placed, or fighting the UI to place some text inside the box I drew.

However, even seeing a Visio genius create a sequence diagram - creating complex sequence diagrams in PlantUML is so much faster, in my mind.

What I do like about PlantUML is its ability to do multiple diagramming formats, and support for things like icons, etc. Unlike GraphViz, PlantUML isn’t just for graphs.

Dia diagram editor

The Dia Diagram Editor is a cross-platform, free, Omnigraffle with bad UX.

I find it both hard to get into the flow with this tool, and creating even medium complex documents seemed to burn an afternoon.

At this point I would mostly only use it if I had no hand drawn tools at my side, and I cared deeply about exact object placement.

[Update]: Scapple

I was having a conversation the other day and was reminded about Scapple, from the company that makes Scrivener, the popular writing tool.

Scapple is great when I have an mindmap I want to create quickly, but I want exact placement over where the elements go, and I think that halfway through my mind mapping work I might want to switch to paragraph sized text chunks. (Think almost suddenly realizing you need to hang sticky notes off a mindmap you’ve drawn).

So it’s really good for that uncertain work: rapid development of a mindmap but I can break out into larger concepts (and not just one word) if I have to. For example, I used Scapple to create the diagrams in Herds of Microservices and Flocks of People.

Emacs Artist Mode

M-x artist-mode

then use the Artist menu to select what tool to use

This is OK if the diagram is going to source control, but it falls down a couple ways:

1. no infinite canvas
2. If you mess up (aka need a box to be shifted left or down) there doesn’t seem to be a way (or I’m not a very good emacs user).

You can export these to smooth pro looking graphics with ditaa.

If I was writing an ASCII diagram in some code comment I’d be interested, but for general use no thanks.

Also ran: OmniGraffle

I am really fast with OmniGraffle, having used it since maybe version 2. OmniGraffle also has this neat outlining feature where I can use an outline to build my mindmap, then let Omnigraffle arrange the nodes somewhere useful. Sometimes I see very interesting patterns that I would have never thought about by letting the computer arrange clusters or hierarchies in some algorithmic form.

This is, of course, assuming I was on MacOS all the time, as previously stated.

For year end and mid-year evaluations usually I keep a mindmap of my responsibilities in OmniGraffle. It’s in general an understanding of the characteristics of the work world around me, and given my leadership role it’s kind of big. Probably too big to easily do in GraphViz.

It says it imports GraphViz, but it fails at all but the most simple diagrams. I don’t think I’ve ever gotten it to work.

Also ran: (MS) Whiteboard

More collaborative than anything else. I want so much to use this, but haven’t in reality.

imports into OneNote OK

Also ran: draw.io

I’ve seen people use it, I haven’t.

Conclusion

I lean towards tools that allow me to put the interface away and get stuff done quickly. While pretty is important, for my technical work it takes third place to (a) getting state out of my brain (b) into a format appropriate for my audience.