Technical Writing - Is It A Worthy Role?
In software development most of the limelight usually goes to the developers, contributors, and project maintainers. But are other tasks — especially documentation — any less worthy?
In this post you’ll learn what it takes to write a great tech blog post — in 5 simple steps.
Tech is something I never get tired of. Whether it’s new software languages, new hardware, new tools or new concepts, it’s in my blood. But just because it’s in your blood doesn’t mean you can write about it.
Don’t believe me? Think of a handful of people you know, who are good, or at least, very, passionate about what they do.
Now of that list, would you ask any of them to tell you about what they do? How many would put you to sleep? How many would talk over your head — almost immediately?
Whilst well meaning, and very capable, most techs (geeks and nerds are also applicable terms too) just can’t communicate that well. Sorry folks, but I have to be honest!
When I say I’m a freelance technical writer, with over 14 years of software development experience, people are so often amazed that a developer can communicate and teach what they know.
It’s much more common place for developers to have no desire to communicate, to take forever to compose their thoughts, or just completely miss the mark when attempting to do so.
My brother refers to what he commonly hears from support staff as “Talking in Modem”. I didn’t quite know what he meant when he used the term. He clarified by saying:
You know that noise the old modems made when they’d connect to the internet, that squeaking sound at various pitches? Yep, that’s what it sounds like a lot of the time
So today I’ll show you what it takes, even if you’re a tech, to write a great tech blog post; in 5 simple steps. Consider it a crash course.
If you don’t have this skill, or are unwilling to develop it, the rest doesn’t really matter. Yes, you can explain step-by-step how something works.
But that’s not teaching, it’s not communicating. This approach doesn’t really help someone truly learn.
You have to be a storyteller.
You have to wrap up tech in a story which draws people in, then hooks them, taking them along for the ride, engaging their imagination.
To help you start off, ask yourself the following questions:
In short, look for the benefits, not the features. Find the hook then craft your story around it.
This is the next most essential skill to master. Tech’s one of those gorgeous subjects where, if you’re not careful, you can attempt to talk about too much.
Everyone seems to want to know everything, especially about anything new. Fine if you want to, but you’ll lose your reader; lose them by making it too damn hard to stay focused on all the things you’re trying to cover.
Don’t do it. Instead pick your topic, one topic, perhaps along with some minor, supporting, one and focus right in on it, bringing it to life in full technicolor.
If there’s one thing that technical people don’t like it’s waffle. We’re the kind that like to get to straight to the point, get the facts, know what’s going on. So for that reason, you have to know and respect your audience.
Sure, tell a story, but take more of a Hemingway than a Shakespearean approach. Build the scene, but not at the expense of the facts. Use a story to bring out the tech core, not to obfuscate it.
Another thing about tech, which I’m sure we’ll all agree on is that it changes so damn fast. So make sure that what you write about is timely.
Don’t talk about outdated software versions or previous software releases. Like everything there are exceptions, such as historical or yearly reviews.
But for the most part, make sure your finger’s on the pulse. Talk about up to the minute topics, like the latest version of Android, iOS 8 and OS X Yosemite (latest at the time of writing).
Demonstrate that you stay up to date with what’s going on.
Here’s another essential — if there’s one thing which can sink you, it’s technical errors. You’ll frustrate your readers no end as they’re trying out code and configuration changes, only to be met with errors.
Don’t be the person who always makes mistakes, who get things wrong. Be the person people can always rely on for accuracy and quality. Be the person who stands out from the crowd and presents information which works, first time, every time.
And that’s 5 tips for writing a great tech post. Take these on board and you’ll definitely gain greater traction with your readers.
Do you have other tips and ideas for great tech content? Share your thoughts and experience in the comments.
In software development most of the limelight usually goes to the developers, contributors, and project maintainers. But are other tasks — especially documentation — any less worthy?
Recently I dateed my first book, Zend Framework 2 Foundations and I’m really excited. Not only is it on my
I’ve been a software developer for close on 14 years now. But for only a precious few moments during those
Looking for an application giving you the ability to organize your writing like sheets of paper, with the power of a web-based app? If so, I’ve got the answer!
Please consider buying me a coffee. It really helps me to keep producing new tutorials.
Join the discussion
comments powered by Disqus