How I Write : My End-to-End Process

An interesting question came up on Mastodon, asking people to describe their writing process.

I write for a living. Most of my writing is for technical websites, but I also accept private commissions for businesses. Just in case my writing process is of use or interest to anyone else, I thought I'd describe it here.

Typically my articles are what we call explainers. They do what they say. They describe a process to the reader. For me, usually this is how to use a Linux command, or how to achieve something on the Linux command line in a terminal window. Occasionally I write op-eds which are editorial articles, expressing my opinion about something.

My writing process is always the same.

The First Step is Research

I do as much background reading and research as it takes for me to feel comfortable about the subject. For Linux, this usually isn't that much - I've been using Linux for over 20 years - but if the topic is something I haven't touched for a long time I need to check that it hasn't changed since I last looked at it. I can't assume my knowledge is 100% up to date.

I use free software called Zotero to collect the references from every bit of source material I use. Zotero is great. It runs as an application on your computer and is also accessible anywhere from within a browser. It lets you search your database of references, and you can also add tags to references.

These are free-format, and you can add as many to a reference as you like. For example, you might categories all references that have anything to do with Git with a tag called "git", and then add a secondary tag such as "merge" or "rebase" or whatever, according to the topic of the reference. Needless to say, you can then filter by tag.

Zotero is a fantastic research tool. It is even able to integrate with LibreOffice Writer and Microsoft Word, and can insert references into your work and generate bibliographies in any of hundreds of publication styles. That's great for students and academics, but it isn't anything I need to do any more.

Just being able to quickly and painlessly create a searchable database of references is invaluable for me. Most references are added with a single click, and to be able to go back and check out every scrap of source material I've ever used - whether I've actually referenced them in an article or not - is truly powerful.

Zotero is available for Linux, Mac, and Windows, and it is free. You also get 300MB free online storage, for a remote copy of your database. This provides an off-site backup, and it also lets you access your database from any browser. If your database grows larger than 300MB you can increase this to 2GB for $20 a year.

So, that's the research done, and the references managed.

The Walk-Through Stage

If I'm writing an explainer, I need to actually do what I'm writing about so that I can capture screenshots of the process. These do several things.

1. They illustrate and help explain the process. This makes the article more useful to the reader. If required, I can edit a screenshot and highlight something that I want to draw their attention to. I use free and open-source software called Gimp to edit images.
2. They prove that if you follow the steps correctly, the process actually works.
3. They prove I'm not just making this stuff up and bluffing my way through.

Sometimes I need to set up virtual computers with the appropriate operating systems, or to configure them into a particular type of network or other configuration.

When I write about a Linux command or piece of software, I describe it for Manjaro Linux, Fedora Linux, and Ubuntu Linux. These cover the three main Linux families (Arch, RedHat, and Debian). Being this thorough means what I write is accurate and correct, but it does mean I have to check everything on three operating systems. The upside is, readers know that if I say something, they can take it as gospel.

The Structuring and Planning Phase

I'm a big fan of mindmaps. They suit my thinking processes. I use a free piece of software called Minder to generate my mindmaps.

They let me quickly capture main ideas and position them on the screen in a way that shows the relationships to one another, and to add sub-topics - and sub-sub-topics - or whatever makes sense to me, anywhere on the colour-coded map.

I also use it for planning software, and for planning the documentation for the software.

The Write-Up Stage

I finally get to commit the article to paper. Or more accurately, to type away in an editor. I write in something called Markdown, which is a lightweight text-encoding scheme.

The advantages of this are I can use a plain old text editor. Any text editor can be used to write in Markdown. Markdown is just plain old text, with some text-based formatting instructions in it. This page was written in Markdown. It features, titles, links, numbered lists, and so forth.

Because you can use a plain text editor, you can work anywhere, on any computer. You're not restricted to working on computers that have some specific, dedicated software such as Word installed. Text files are small, fast to transmit and backup, and you can use a real version control system like Git.

The editor I happen to use is Sublime Text. This is a paid-for, commercial editor. There are a gazillion free editors - especially on Linux - so why do I pay for one? It's because it is the best programmer's editor I've ever used. And because I also write software and I use Sublime for that, I use Sublime for everything else, too.

While I'm writing the article I add links to some external references such as home pages for software I'm talking about, or other useful resources. Often, websites want to have links to other articles they've previously published that have some relevance to the new article.

Once I've written the article I use another free piece of software called pandoc. This can convert between many - around eighty - different file formats. With a simple command line command, I can generate a DOCX, an ODT, a PDF, an HTML, or any other format version of the article. I can then distribute these to the client, as required.

Often, when I'm working for an online magazine type of website, they'll have a content management portal they require the article to be entered into. I simply convert my article to HTML, and copy and paste it into the portal.

I don't need to keep any of the PDFs, DOCX files, or whatever. I can regenerate them in an instant if I need them again. So I just need to keep my Markdown file, screenshots, and my Minder mindmap document. Minder is text-based too, its file format is XML, so those files can be stored in Git too.

Then I sit back, breath a sigh of relief, flex my fingers for a few moments, and start on the next one.