Recently, I was working with Misha Tenenbaum as we crafted his product review of the new SpeedScriber product. I enjoy working with Misha. He is smart, enthusiastic and an overall good guy.
As we discussed his first draft of the review, I realized that I had very specific ideas on what makes a good technical article or product review. As I shared them with Misha, he suggested I write an article to share my thoughts with you.
So, here they are.
My feeling is that no one wants to read in-depth on the Internet, they want to SKIM. Hopefully, readers think, the gist of the matter will sink in. This is false reasoning, of course, skimming is not good for retaining specific information, it is better for learning high concepts. But that doesn’t change the way folks use the web.
Still, to make skimming more effective, I break my writing into short chunks – brief paragraphs – with lots of bullets and indents. This creates a very ragged left margin that is harder skim over, the eye keeps “stumbling” into a new line – which allows it to actually read what’s there.
I call this “forcing” the eye to read what I want them to read – and it is more essential in today’s visual environment than ever.
NOTE: The worst thing a technical article can do is present long, solid blocks of text – no one will read them. And full justification should be banned on the web.
I write to one individual, I never refer to readers as a group. Even if thousands of people will read my article, reading is always a solitary activity; one writer talking to one reader at a time.
In my mind, the person I’m writing to is interested in the subject, technically savvy but not about the subject I’m writing about, and easily distracted; which means I need to work to hold their attention.
I use words that include – “we,” “us” – and am very careful using “I” and “you” unless I can use them in a way that makes it seem like we are all on the same team. For example, “I am forever adding new clips to the wrong place on the Timeline, so when you do this, be careful where you put the playhead.”
Over the years I’ve learned never to talk down to an audience. There are always people in it who know more than I do.
The biggest mistake most writers make when writing instructional materials is assuming that their audience has a clue as to how something works.
NOTE: A good example is trying to give directions to someone wearing a blindfold. You instantly realize that your steps need to be simpler, much more direct, and delivered in clear language.
This is why I like using many screen shots. When I write “Click here,” the image shows exactly where to click, along with a written description of what to expect when you do.
Put An Executive Summary Near the Top
There are two types of people who read tech articles:
Most readers are in the first group, while people on the edge of a buying decision or trying to get something to work are in the second.
To this end, all my product reviews include an Executive Summary at the top so that “skimmers” can get the information they need without reading the entire article.
There’s a second big benefit to an Executive Summary near the top – it positions everything else I will cover in the article. Readers know, going in, what the article is about, what it will discuss and the overall conclusion.
Explain the Basics
This gets me to my second point: define terms and provide a foundation so that people understand what you are talking about before plunging into the fun new stuff.
It drives me nuts when I am reading an article and I have no idea what the writer is talking about. Providing a general orientation to the subject doesn’t take more than a few paragraphs and means that readers with less understanding of the issue can still appreciate what is being discussed.
I find language fascinating; but that doesn’t mean I should turn a technical article into a college treatise.
I make a big effort to define all unusual terms, then write using language that would be appropriate for a college freshman. (Well, OK, that’s my goal, but sometimes words are so cool that I just get carried away. I have been known to read a dictionary for its plot.)
The tech world is hopelessly littered with jargon. However, that doesn’t mean you need to contribute to the mess. Define all acronyms and key terms. Then, be consistent in your usage. For example:
When writing a product review, there’s a very specific structure I follow:
I try, in my reviews, to express a personality, but limit expressing my opinions until the Summary.
Do everything you can to make it DEAD EASY for someone to skim your article. Short, simple paragraphs, set off with informative subheads.
If someone is skimming, they’ll stop when they see a subhead that appeals to them. And, if not, that’s fine, too. That’s what the Executive Summary is for.
Screen Shots and Photos
The more examples, illustrations and images in your article, the better. Nothing explains like a picture. Plus, images are fun to look at. However, take the time to crop every image so that it shows precisely what you are talking about. Help the reader find what they need to see. There’s nothing wrong with lines and arrows that indicate key points.
Photoshop has excellent image cleanup tools. Use them to get rid of garbage in the image that detract from what you are trying to say.
Screen shots of copyrighted software can be included in an article reviewing that software or creating a tutorial for it without requiring permission of the copyright holder under the terms of Fair Use.
Also, my style is to put the screen shot ABOVE the text that it illustrates. In my books for Peachpit Press, they wanted screen shots below the text. Both are OK, just be consistent and, if necessary, explain what you did.
At the end of a highly technical article, I’ll add links to related websites that explain a subject in greater detail. My articles generally run between 1,500 and 2,000 words. If more detail is needed, I’m happy to refer people to additional sites.
Yes, that may cost some web traffic. But, my goal is to inform and educate, and, sometimes, that requires referring readers to other, more detailed, websites.
MY PERSONAL RULES
Writing a technical article or review isn’t hard, it simply requires an understanding of the subject and an ability to explain it clearly to others who are interested in learning more.
Well, that, and lots of practice. And a readership that isn’t shy about pointing out mistakes. Frankly, its a fun gig.
As always, I’m interested in your comments.
NEW & Updated!
Edit smarter with Larry’s latest training, all available in our store.