I enjoy writing how-to articles, and I thought I’d share my simple workflow. After you have an idea for an article, the process is straightforward with only three steps.
Step 1 — Outline
Step 2 — Add Details
Step 3 — Review & Polish
Step 1: Outline
For how-to types of articles, a simple set of actions, notes, and references is all it takes. Keep everything in order as much as possible, especially if you’re not going to execute all the steps again before sharing them. Here’s an outline for an article about setting up OpenVPN on AWS taken from my drafts.
Anything you consider important should be in the outline, such as:
- Necessary references or links
- If it helped you in some way, jot it down, later you can decide if it’s worth including in the how-to article. As you write more articles, you’ll naturally narrow down your outline to only the most relevant parts.
- For example, I noted spinning up an Ubuntu Linux instance in the outline, but in all practicality, it probably doesn’t need to be an Ubuntu Linux distro. This can be decided when fleshing out the details.
- Steps that can’t be skipped
- Like sudo su. It’s best practice to not run as a superuser all the time, and when recollecting steps while writing an article, this is an easy one to accidentally skip over.
Step 2: Add Details
When the AWS OpenVPN article is finished, I’ll add a link here. An example how-to article can be found in my writeup about how to connect an iPad to a digital piano wirelessly. As you detail the steps, make sure to add an opener and brief conclusion to wrap things up. The following format is simple, yet predictable.
Article Format
- Identify the purpose and goal of the article
- Add an opening paragraph describing why you are writing the article and the end goal the reader should expect to achieve
- Include appropriate prerequisites
- Provide detailed how-to steps, identifying possible roadblocks along the way
- Add descriptive text, screenshots, examples, and common issues that people might run into.
- Avoid filler text
- Wrap it up, nothing fancy
- If applicable, follow the article with relevant links and references
Additional Detail Examples
In the sample outline above, one thing I didn’t specifically call out is that I was setting up the OpenVPN service to utilize AWS’s T4g line of instances that run on their Gravaton2 64-bit ARM-based processors. They’re efficient and extremely cost-effective, but they aren’t necessary to set up OpenVPN on AWS. This can all be noted when talking about the purpose of the article in step 1.
Another thing I noticed in my screenshot was the orange bar at the top, which most people won’t have or be familiar with. Depending on the article, I’d either leave that out, as it has nothing to do with running OpenVPN on AWS, or I’d add a mention informing readers of the added layer of security using Cloudflare Access to protect the admin section of a WordPress site.
Step 3: Review & Polish
Accuracy
It’s not always practical, but following your article from start to finish to ensure technical accuracy is ideal. You may run into an “oh right, I had to do that other thing too…” situation. Your readers will appreciate this, I promise!
Writing Quality
An amazing, sharp copywriter I’ve worked with in the past suggested using a writing assistant tool like Grammarly or LanguageTool. Both of these companies offer great free versions, and if you write for a living, the paid version would be worth the deep insights. I was a bit hesitant about this extra step at first. Then, I went through my long post on How to Make a Stage Boat equipped with Grammarly, and wow, it was worth the extra effort. It quickly highlighted my tendency to use extraneous words like really and definitely too often.
Final Thoughts
Now that I’m wrapping up this how-to article on writing how-to articles, I just went back through to make sure I’m eating my own dog food. I haven’t done my Grammarly review yet, but it looks solid; it’s just about ready to publish. I’m going to add another image or two between the outline screenshot and the Grammarly screenshot to help break up the text content.
While pondering the intangibles of how-to articles, I considered gut feelings. If the article doesn’t feel complete, it probably isn’t. If you’re not in a rush to publish it, move on to something else and pick it back up a day, a week, or a month later. After some time, it may be clear what was missing. If you’re in a hurry, get a friend or acquaintance to review and provide candid feedback.
As a final note, if you’re reading this, there’s a good chance you may be writing your own how-to article. I always appreciate clear, well-written how-to’s from the online community and just want to say thank you for sharing your knowledge with the rest of us!
