Writing tools for software developers

August 6, 2021

I’m hardly the first to observe that the further a software developer gets into their career, the more their job requires communicating, as opposed to simply writing excellent code. And as workplaces are starting to get more remote- and async-friendly, that communication tends to become more written than spoken. So developing your writing practice is a critical career skill.

But why give up your excellent coding toolset just because you’re writing in a different language, right? You worked hard to gain your current level of editor wizardry, and writing can benefit from version control just as much as code can.

Here’s a quick list of coder-oriented tools I use for writing.

Markdown (markup language)

It’s the fashionable programmer’s markup language. I’m fluent with Markdown, so I tend to prefer tools that support it.

I’ve been looking into reStructuredText, and I could be convinced that its technical merits exceed those of Markdown, especially in the area of extensibility (e.g. name-based linking within a site, such as a wiki or docsite). But nothing beats Markdown for sheer popularity. And, well, I’m invested now.

Joplin (note taking app)

I use Joplin for drafting and note-taking. It’s how I keep track of a lot of the stuff I do: ideas for writing, projects at work, toys or gear that I’m keen to try, triathlon training plans, all of that.

I started using it because I was sick of Evernote. There were a few reasons:

• Its formatting was clunky, especially for code samples.
• Having my personal notes stored by a corporation was not my favourite.
• They constantly nagged me to upgrade, even though I was paying them money.

So I looked for something free, Markdown-y and with support for self-hosted syncing. Et voila!

I also like Joplin’s inbuilt support for Mermaid diagrams – we’ll get to that in a moment.

Just for giggles, I would love to have Evernote’s OCR capabilities in Joplin, though I’m not quite ready to go the machine learning route to get them. I’ve read that plugins do exist for that. I’ll have to try them out some day.

Mermaid.js (diagrams)

Mermaid is a plain-text language for making diagrams. I love it because it solves several problems I’ve had with so many diagramming tools:

• They’re usually graphical, which means I need to use a mouse a lot. If there’s a thing I hate, it’s too much clicking.
• They usually require a separate program (or webapp) to edit. This disrupts the flow of writing, and makes the written product and diagram harder to maintain.
• The diagrams usually can’t be inlined into the article. Instead of one plain-text file for my article, I now have one text file, plus one or more PNGs or something, which can be hard to associate back to the articles that include them. That can be solved with discipline, but discipline like that is hard to maintain for me, let alone my entire team.
• Their output is usually binary, making them work poorly with the version control tools I like to use when I can.

Mermaid is a plain-text format that seems to do for GraphViz what Markdown does for HTML. It supports a few different types of diagrams, though I mostly use the graph type to draw boxes and lines. Mermaid source is easily inlined, and a bunch of Markdown-y tools have plugins or extensions for supporting Mermaid too.

Excalidraw (whiteboard, diagrams)

As great as plain text is, you do sometimes need a graphical diagramming tool. Excalidraw is the best one I have come across so far.

• It has a bunch of keyboard shortcuts, meaning I only need to mouse for drawing.
• It can produce “drawn look” diagrams, which help to suggest the intended level of precision for a lot of stuff I make ;)
• It’s self hostable.
• The hosted version supports collaboration – I’ve used this for pairing, remote interviews, and a few other things.
• It’s not hard to pick up and use for the first time, like your Visio or whatever.

I actually just found out about a cool Excalidraw feature today. Apparently, if you copy-paste some 2-column CSV data (or data from Excel or a HTML table) into Excalidraw, it will automagically chart it for you!

Reveal.js and reveal-md (slides)

Reveal.js is a framework for writing slide decks in HTML and presenting them in the browser. It also does a nifty thing where you can navigate in 2 dimensions; slides can be grouped into columns, instead of running from start to finish in a single line.

Making slides using only a text editor and a browser? You better believe I love that. In fact, there’s only one thing that could make it better – Markdown!

Enter reveal-md. This takes the features of Reveal.js and makes them available in (slightly extended) Markdown. Instant happiness!

This pairing is my go-to for slide making. Especially since I added some special sauce for embedding Mermaid diagrams in my slides

As an added bonus, reveal-md slide documents will work with an ordinary Markdown renderer. So with some well-written speaker notes, you can also use your Markdown to produce an acceptable (though not amazing) print document.

Honorable mention: MkDocs (documentation)

I only started playing with MkDocs recently, so I haven’t had time to run into many of its quirks. But I have enjoyed a reasonably smooth experience while putting together a doc site for my team.

MkDocs is a static site generator. In its default configuration, it produces sites that look a lot like readthedocs.ioYes, those are the docs for ReadTheDocs . As you might imagine, it’s Markdown-y. It also supports plugins for extending the Markdown syntax in all kinds of interesting ways (if you need that).

So there you have it! Hopefully one of these little gems brightens your day