Blogging. Many of us in the technical community do it. It’s a way we can document our successes (and failures), prevent others from making the same mistakes we did and become an important part of our resume repetoire.
When I first started blogging nearly 11 years ago, I spewed out text onto a page that seemed coherent at the time. In my head, it made sense but years later looking back I realized a monkey dancing on a keyboard could write better.
Why were my blog posts so bad? It wasn’t grammar. I’ve always been pretty good there. If not grammar, did I get the tech specs wrong? No, not necessarily. I usually double-check to ensure what I present is technically accurate.
Then, what was it? Every post lacked a few key attributes.
Table of Contents
Be Specific
One of the most common mistakes I see new technical bloggers make is not being specific enough. They succumb to the curse of knowledge and lose their readers a few sentences in.
They’ll lack specificity in two areas:
- skip over important training concepts that a beginner needs to have
- Refer to demonstratives like this, that, these, etc that I refer to as ‘pointer’ words.
The first, and most important, is skipping over concepts that leave a beginner confused. Perhaps you’ve been working with Active Directory for 20 years and decide to write a blog post on how to create a new user account. You don’t pay attention and immediately jump into the new user wizard in Active Directory Users and Computers (ADUC).
You’ve already lost some readers because ADUC isn’t installed by default in Windows. How does the reader obtain ADUC? Where would they find ADUC to get to that wizard?
Another example of lack of specificity is in the grammar. Many bloggers (me included), have a habit of using too many demonstratives like this without enough context. These ‘pointer’ words, as I like to call them, point to another term or concept. This forces the reader to remember what ‘this’ refers to.
For example:
Click on the button to save the file. This saves the file to a location.
What does ‘this’ refer to? The button? The action of clicking the button? Instead, you should be more specific and call out what ‘this’ is “pointing” to.
Click on the button to save the file. When you click on the button, the software saves the file to a location.
You may find this strategy cumbersome, wordy and unnecessary. We’re all inclined to take shortcuts but trust me, your readers will thank you.
Teach, Don’t Just Show
The reason my technical blog posts sucked was that I thought technical how-tos and blog posts were the same things. Sure, my blog posts showed the reader how to get from point A to point B. But the article read like an RFC document full of dry, to-the-point information that made great bedtime reading.
Traditional software documentation that teaches a reader how to do something is dry, boring and not engaging at all.
The reader follows the directions step-by-step and, if each step were performed correctly, they have a working widget. This model is great for drones that could care less what they’re actually doing; not so much for actual people.
Most people come to a blog to learn, not just to do. They want to know how to do the thing but they also want to learn why they’re doing this in the first place. They want to learn context, pick up a neat trick along the way and be entertained while doing it.
Readers want to be engaged, entertained and learn. They want the entire package. You’d think your only audience were millennials!
Let’s say you’re writing a blog post on how to set up a new piece of software. The setup process takes a few steps that include downloading a file, running an installer and so on.
Compare the following two versions:
To set up software X, follow these steps:
1. Download the file and save it to C:\ImBoring.
2. Next, double-click on the file.
3. When the installer opens, click Next…
or
It’s time to set up software X! Doing so involves a few steps. But, follow along with the steps below and you’ll be well on your way to <what software does for the reader>!
You’ll first need to download the file and save it to C:\MuchBetter. Once the file downloads, double-click on it. This brings up software X’s installer. Although a bit confusing at first, once you get the hang of it, it’s not too bad.
You’ll see a Next button on the installer window. Click that button and…
Notice the first version was a numbered list. Numbered lists are OK in some situations but tend to fall into the “Wow, I’ve got 99 steps to follow here! I’m out.” category. The second version has no numbered list and walks the reader through the steps in a casual manner.
Technical blog posts don’t have to be dry, to-the-point material. Bring yourself and your own personal style. Be funny. Be unique!
Make Your Post “Flow”
As you saw in the previous section, many new technical bloggers writing how-to content start with the numbered list approach. They want to show the reader how to do something. They provide the necessary steps with nothing extra. Efficiency achieved! This kind of thinking leads to “jerky”, start-and-stop content.
- Do this.
- Do that.
- Click that.
- Type this in.
Great blog posts should flow like a river not like a car in heavy traffic.
Include transitions between elements and add little summaries at the end of each section. Do anything you can to make the blog post ‘flow’.
Let’s say you’re working on that software X how-to blog post mentioned earlier. Overall, the blog post has three main sections; installation, configuration, and deployment.
A stop-and-go approach might look like the following:
Installation
1. Download the file.
2. Click on the installer.Configuration
Type in the name of the application in the FOO field.
Deployment
Now deploy the software to your computers.
On the other hand, a ‘flow’ approach would like this:
Installing Software X
Once you’ve got all of the proper prerequisites, it’s time to install the software. To get the software installed…
xxxxxxxxxxxx
Now that you’ve installed software X, it’s time to set up XYZ feature.
Setting up the XYZ Feature
Installation was pretty easy but setting up isn’t quite as so. If you’re not scared off yet, let’s jump right into it.
xxxxxxxxxxxxxx
You survived! Congratulations! One more step. I promise.
Deploying Software X
So you’ve installed Software X and survived the set up portion. Now comes the easy part; deployment… <and on it goes>
Notice how I have transition sentences between the sections? These sentences piece together the content. The instruction comes across as conversational, casual and reads like a journey the reader is on vs. a series of unrelated tasks.
Conclusion
Writing engaging, entertaining and technically accurate content is hard. Most of the time, the ones with the technical know-how cannot write and the ones that can write don’t have the technical know-how.
It’s always easier to teach an engineer to write than to teach a writer to engineer.
If you’re an engineer, take these tips to heart and start teaching your readers! If you’d like to learn more about these concepts, check out my eBook, Teach Me: How to Write Technical Articles that Make Money. I go in depth on many of these topics and making a few extra bucks never hurt either.
