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:

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:

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.

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 :grinning:

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 :slightly_smiling_face:

Writing tools for software developers - August 6, 2021 - Lucas Wilson-Richter