Recently, several of my technical friends have spoken to me about their blogs, saying that they lack confidence in their writing style. They asked me for advice on how to improve their technical blog writing, so as the editor of ViewsHound, and a software developer myself, here’s my top tips for technical blog writing:
1. APT: Audience, Purpose, Tone
I learned “Audience, Purpose, Tone” during my A-levels, and it was probably the most important thing I learned in the whole two years! I recommend this tip to everyone who I help with their writing, and it never fails to improve their work. Just spend a minute thinking of this before you write. It’s very simple:
- Audience: Who are you writing for? What knowledge and skills do they have?
- Purpose: Why are you writing? To inform, entertain, persuade?
- Tone: What attitude will you take? Friendly, harsh, formal, relaxed?
There’s not much to say about tone, but let’s look at audience and purpose in more depth.
2. Audience: Don’t fall between two stools
One of the most common failings I see with technical articles is that the author has no idea of who his reader will be, so the article swings wildly between being too basic and being too advanced. As a result, the article is no use to anyone. So decide right at the start whether you are writing for novices or for advanced readers, and stick to it. You can explain a few terms as you go, to broaden the appeal of the article, but decide how much knowledge your reader is likely to have *before* you start writing.
3. Purpose: What is the benefit to the reader of your post?
Another common mistake in technical blog posts is to forget why you are actually writing! You always want the reader to come away from your article with something: knowledge, an opinion, an emotion, a better impression of you, etc. So before you start to write, figure out what you want your reader to do at the end of the article. It’s not complicated: in the case of this article, all I want is for you to come away being able to write better blog posts (and, as a result, increase the traffic to your blog).
4. Write your headline and summary first, but check at the end
Writing your headline and summary first will give you clarity, give you a focus for your article, and will help to keep you on track. (Some blogs don’t have a summary, but articles like this one do.) After you finish writing the article, go back and make sure you didn’t drift, and then either reword the article or change the headline/summary to make sure you’re still consistent.
Good headlines are hard to write—I toyed with about ten before I settled on the one I used here, and it’s still not perfect. However, in these days of Reddit, Hacker News and other aggregators, you often *only* have the headline to make someone decide whether to read your article or not, so it’s worth spending the time on a good headline.
5. Plan before you write
If you set off into the unknown without a map (or, let’s face it, without your phone!) you’re going to get lost. That’s exactly what happens to a lot of bloggers. The post meanders, never really goes anywhere, and most people will stop reading. The solution is to make a plan.
Some people find it hard to believe, but good planning doesn’t *cost* time, it actually *saves* time. All I did to plan this article was to grab a sheet of paper and a pencil and jot down the subheadings for the things I wanted to say. (I prefer planning on paper, where I can quickly scribble, cross out, draw arrows, etc, but it doesn’t matter how you do it.)
6. Use a story
When children are small, they all have stories read to them. As adults, many of us read fiction and watch films. The desire for stories and narrative seems to be hard-wired into us. So if you can weave a story into your article, so much the better. You don’t need to be the next Stephen King, a few sentences will do. To start this article, I chose to tell the story of why I was writing this article, and it took me literally one and a half sentences.
Your technical writing will come to life if you can bring in stories and human experience, without rambling or being long-winded. It’s often enough to explain the story as to why you happen to be writing your blog post. What chain of events—meetings, failures, successes—led to the thoughts you are now writing about?
7. Use subheadings for structure and to break up the text
Subheadings are under-used. I think this stems from school, where you had to write essays with no subheadings. Well, like a lot of the useless junk they taught you at school, ignore that and get some subheading action going!
There are three main uses for subheadings. First, they give structure for you as a writer, and help stop you from wandering off at futile tangents. Second, they signpost to the reader what is coming up, to help the reader make sense of your work and place it into context. The brain takes in information better if it understands ahead of time what it is going to be learning, and a subheading lets you do this. Third, a subheading is a cosmetic device to break up large amounts of text. It’s just more comfortable for the reader if you use regular subheadings.
As a side point, you can use little signposts like “First, second, third”, as I did in the paragraph above, to almost act as mini-subheadings and keep things on track.
8. Use fairly short paragraphs
As with subheadings, it’s easier for the reader of a blog if you keep paragraphs short. Paragraph length isn’t as important if your work will end up on paper—in a book or magazine—but for reading on screen short paragraphs help keep the eye from physically wandering. There’s no hard and fast rule, but five sentences or so is a reasonable length for a paragraph.
9. Back up your opinions with facts and links
A popular failing of bloggers is to state opinions without backing them up. Use facts, with links to the sources, wherever you can. The more authoritative the source, the more useful the fact or link will be in helping you to make your case. Wikipedia is OK to quote, but not great; it carries weight in the eyes of a lot of people, but of course the content is open to being abused. If your readers trust your sources, they are more likely to trust *you*.
10. Lay your work to one side, and proof read later
You should always proof-read your work before posting it. I always like to lay my work aside for a few hours, or preferably a few days, before coming back to it to proof-read it. If you allow time for your brain to recover from writing, and then come back to your post afresh, you will find mistakes, poorly-worded phrases, things that don’t make sense, and all kind of nasties! So unless you’re desperate to rush something topical onto your blog, it’s worth the wait and then doing a proof-read.
Bonus: Write your blog posts in Microsoft Word or Open Office
Whether you use Microsoft Word, Open Office or another product, just be sure to write in an actual word processor. This way you get a spell checker, and a grammar checker (which is mediocre but better than nothing). I recently exchanged some emails with a person who wrote his articles in a raw text editor, and they needed a lot of editing, much of which he could have avoided by writing in a word processor.
Final thoughts
These tips are all simple. Hopefully they’re all obvious too. There’s really nothing complicated here, but if you focus on these things your technical blog writing will noticeably improve, and so should your traffic.