My (current) blog article writing process

As with my work, when I write articles on my blog, I have a focus on quality. Here I describe my current writing process, primarily to document things for my future self.

I have ideas. Lots of ideas. Unfortunately, too many to chase all at once. When I follow the thread of a particular idea, I stumble across many interesting problems to solve. This can be as part of my work or simply when I’m trying to get stuff done.

These ideas and and their solutions provide the inspiration to tell a story about what happened, why, and how to resolve the situation. Often, the impetus to write this stuff up comes from a compulsion to help others: someone else might have had the same problem and is searching for a solution. It’s cool to have a worked solution already written up that can be used directly. Sometimes this “other person” is myself. More than once, I’ve googled for a solution to a problem only to find said solution written up on my blog. After all, as Damian Conway once said: documentation is a love letter that you write to your future self.

This article describes my current writing process, how I find things to write about, how they turn into articles, and how I polish the text to focus on quality. The process is very much in flux, and I’m still on a learning curve, so I expect things will change in time.

To be honest, I never liked writing stories at school. This is one reason why I became a scientist, so I didn’t have to keep writing silly stories.¹ It turns out that that’s part and parcel of being a scientist. Bummer!

It also turns out that a well-written explanation can be very helpful. And–after many years of trying to avoid such tasks–I finally realised that writing isn’t so bad after all. It’s a hell of a lot of work, but then that’s the case with many worthwhile things.

Obstacles are story germination sites

A lot of what I write about stems from some task I was trying to solve or some kind of (usually technical) obstacle I was trying to overcome. Once at the end, I sometimes think “Hrm, this might be useful to someone else”. Thus, a story forms, explaining how the problem arose and how I managed to solve it.

Solving a technical problem is a lot like puzzle solving. When I solve such puzzles, I make copious notes so that I can explain what happened and why. The reason for my note-taking stems from a desire to write good commit messages and have thorough documentation of the problem. Since this is usually some kind of software-related issue, I dump all that I’ve learned into the project’s issue tracker. This way, others can see what did and didn’t work, transferring knowledge and ensuring anyone following in my footsteps has an easier time in the future.

My commit messages have come back to haunt me in both positive and negative ways. The negative ones are usually a message like “Fix obkus leak in frobniator”. Gah! Tell me how you fixed it and why! The positive ones, on the other hand, contain enough detail and explanation for my future self to work out what was going on and how to fix things again, should this be necessary. When I stumble across a good explanation from my past self, I’m frequently stunned at how useful the text is and how much pain and stress it relieves. Damian’s quote rings very true: these really are love letters to your future self.

Reworking a solution

The notes themselves, either in commit messages or in issue trackers, aren’t always useful in the form that I initially wrote them. They contain lots of dead ends, extraneous details, failed experiments, and wild goose chases. They lack a “red thread” from problem to solution. This is why I write up an article about some problem and its solution; I work through the puzzle again (sometimes a couple of times) so that the path is clearer and more direct. My thinking here is that someone reading such an article doesn’t want to go down the same dead ends as I did. Dead ends can be useful, but only if someone puts a signpost in front of them to say, “I tried this out. It didn’t work. Don’t try this at home.” Re-working a solution also helps me shed unnecessary detail and sometimes shows me an even better way to solve the problem. My hope is also that the article’s text flows more logically and that the steps from beginning to end make more sense. Either way, it’s a necessary step to redo things and see that, yes, this was a good way to solve a particular issue.

In working through the problem again, I start writing the first draft. Often, each step only requires a few words to tie things together. Install that, edit this file, use that setting, restart that service, and Bob’s your aunty’s live-in lover. In such cases, the article “writes itself” from the initial notes and the example run-through. However, I find that only the basic structure takes shape at this stage. The real hard work starts later, in the editing process.

A draft article also needs a bit of explanation up front about what the issue is and why it was so important to solve. It also needs most of the details in the examples to be in place, along with any links to relevant documentation or online resources.

Furthermore, there needs to be some kind of conclusion. I like to round things off by recapping what happened and mentioning any outlook for the future, as necessary. I’ve noticed that some technical book writers tend to avoid a concluding chapter altogether, and the book ends abruptly. This always felt like driving off a cliff to me. As a reader, one has momentum and thinks, “Ok, let’s see what the next thing is the writer wants to tell me”, only to have the book suddenly stop. It’s like Wile E. Coyote standing in mid-air, looking confused and wondering how he got there. Since I don’t like that, I try to round things off, even if the text does seem a bit redundant. It’s like saying “Goodbye” at the end of a phone call. Maybe it’s not technically necessary, but it’d be weird just to hang up.

Let it simmer for a while

After I’ve written the first draft, it needs to sit for a while so that my subconscious can do its thing. I can’t start editing straight away, because I find that I get sort of “blind” to what I’m saying. If I’ve left a text on its own for a few days and read it again, I see all the holes that I need to plug and much of the fluff I need to remove. This isn’t the first time an article needs to sit and “simmer” for a while. Often, after a manual edit cycle, I leave a text alone once more before returning to it with fresh eyes.

Leaning on tools

Editing is hard. Add to that a lack of writing experience, and it gets even harder. That’s why I lean on a couple of tools to support me in this process.

Hemingway

After the first edit,² I use the Hemingway program to check for certain kinds of style issues and for complex sentences. As my school teachers told me back in the day, I waffle a lot. Waffling makes for complex sentence structures, and Hemingway helpfully flags such things. Using a tool like this allows me to reflect and ask myself, “What is it that I’m trying to say here?” Simply having that extra resistance triggers a rethink. Most of the time, I can see a better formulation, which is shorter and clearer.

Sometimes I have to ignore some of the suggestions that Hemingway provides. I found that adhering too much to the tool makes the text stilted and wooden. Somehow, my style of explaining things disappears under a layer of bland standardness. It’s been a learning experience working out where Hemingway can help me and where it can’t. And I’m still learning!

Using Hemingway has helped me to more regularly identify long sentences that need splitting up. I couldn’t see such issues before. Now I spot more of them in the initial edit phase, which is a good thing. It definitely helped me spot when I overuse words like “just”. I’ve found that this can be frequently rewritten as “only”, showing me that I really meant to say something else. Also, it spots things like passive voice, which I try to avoid.

Importantly, the tool notices words that I can omit, reducing the waffle. Mr Rorholt, my economics teacher at high school, would often write the word “waffle!” in red in the margin of my essays, highlighting my poor, problematic–and probably purple–prose. That experience certainly left its mark, reducing, but not eliminating, my waffliness.

Hemingway (the program) does seem to harp on about “simpler phrases” and “unnecessary” adjectives. Sometimes these suggestions have to be ignored. A text without variety and different complexity in phrasing ends up plain boring. Also, it’s not like one can avoid adjectives completely. One needs to get a feeling for when it’s a good idea to follow the advice and when it’s a good idea to ignore it.

A good side-effect of Hemingway highlighting which sentences are complex is that I get an opportunity to cogitate on what it was I was trying to say. The tool isn’t arbitrarily trying to hold me back: it’s providing me with advice. It’s an opportunity to slow down and rethink. Rewriting a sentence or paragraph two or three times can undo any knotted sentence structure that Hemingway spotted. Sometimes, I can remove a sentence completely! After all, deleted code is the easiest to maintain. 😉

Grammarly

While I find Hemingway to be useful as an initial automated check, I find Grammarly gives a text much more polish. The tool has four areas of focus: Correctness, Clarity, Engagement, and Delivery. For me, the biggest help is the Correctness area. It spots typos and spelling errors. It sees forgotten articles before nouns. It detects where I’ve placed commas incorrectly or have missed them completely. It also highlights redundancy, tenses, prepositions, and hyphenation issues. The best help, I find, is the comma fixes. Usually, I re-read the text and realise that, yes, I did intend the pacing to be different and that a comma was necessary to make a pause that I’d not included.

The Clarity suggestions are also great. Often, the simple fact that the text his highlighted makes me look at it in a different light, and I can see an improvement directly. I don’t always need to use Grammarly’s suggestion; the fix is obvious. That’s one great thing about using such tools: they help relieve the blindness one gets by reading a text several times. That’s why putting a text aside for a day or two can be so useful. One sees it with fresh eyes, and a tool can help in achieving that “fresh eye” state.

The suggestions from Grammarly Clarity show how something can be rephrased. This is a great learning opportunity for me. I regularly look at the results and think “Oh wow, yeah, that’s a nice way to say that”. If I see a certain style of suggestion frequently enough, then something eventually gets through my thick skull, and I stop making such convoluted constructions in the first place.

Getting by without a little help from my friends

Support from tools allows me to grow and improve on my own without needing to annoy friends or family by asking for feedback on a text. My two theses relied a lot on help from others. Such tools simply didn’t exist back in the day. Thus, my Master’s and PhD theses were not the work of a single person; they were very much a team effort. I can’t imagine the burden I’d put on everyone if I had them review all my blog posts now as well!

Let it be

Once I’ve completed the initial human and tool-supported edits, I let the text sit again for a day or two so that I can come back to it with fresh eyes. I then go over the text once more and try to spot any issues that might be left over. Sometimes I spot logical problems, sentences that aren’t clear, and phrases that can be deleted. Occasionally, I discover new ways in which something could be better structured.

This is also the time for me to pull out Inkscape and make a cover image. I try to make something relevant to the post’s topic, and I use Creative Commons images and/or the appropriate attribution where possible.

Generally speaking, once a text has gotten to this stage, I’m pretty sick of looking at it, so this is the final edit. I’m rather pleased to move it into my _posts folder and consider it completed. There will probably still be leftover issues or vagueness in the text, but I’ll have to live with that!

Push to publish

And that’s the last step: moving a post from the _drafts folder into the _posts folder. Pushing to my upstream Git repository is then the publishing process. There’s a CI job that runs on GitLab, which handles all the hard work, so I don’t have to do that on my local machine. It’s nice to go git push and think “Ah, that’s finished!”. 🙂

All done

And that’s it. That’s my blog post creation process. Mainly, this was for my future self to look back on my previous self and maybe realise how far I’ve developed. Or perhaps he just wants to remember part of the process. Either way: gudday future me!

1. Like those fun school trips out to Lake Rerewhakaaitu only to have them ruined by having to write a story about it once we got back to school. Urgh. ↩

2. … or edits. I usually make multiple passes. ↩