How I Write Technical Articles or Reviews

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.

OVERALL PHILOSOPHY

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.

THE AUDIENCE

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.

CONTENT

Don’t Assume

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:

• Those who want to stay current on a subject, but don’t care a whole lot
• Those who care deeply and want as much information as they can get on the topic

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.

Language

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.)

Avoid Jargon

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:

• Buttons are clicked, not “clicked on”
• Keys are pressed or held, not “hit”
• iPhone icons are tapped, not “clicked”

FORMAT

The Structure

When writing a product review, there’s a very specific structure I follow:

• Provide a disclaimer, indicating if money or product has changed hands
• Setup the problem
• Provide an executive summary
• Provide links to both the company and the product
• Provide the details
• Wrap up with a summary

I try, in my reviews, to express a personality, but limit expressing my opinions until the Summary.

Use Subheads

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.

Extra Credit

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

• I never accept money from a developer to write a technical article for my website. I have been paid to write articles for a developer’s website and, in that case, I indicate that fact.
• I always indicate if I got the software from the developer for free.
• I always return hardware after a review. Software can’t be returned, but keeping loaned hardware is unethical and smacks of under-the-table payment.
• I will never publish a review or technical article from someone who has been paid to write it, unless I’m the one doing the paying.
• I never show a review to a developer before publication, but notify them as soon as it is published and allow them to add corrections. Showing them a review in advance means you are allowing them to rewrite your words and opinions. That’s PR, not editorial.
• However, I make an exception to this rule for articles on new technology. Here, I may show some of my text in advance of publication to an engineer to get their opinion on whether I’ve explained something properly.
• If it truly IS my mistake I acknowledge and correct it as quickly as possible.
• If it is a difference of opinion, I add it to the review, but flag it: “After I published this review, Mr. Smith, CEO of Developer, wrote to say: “I disagree with your conclusion because it is operating as designed.”
• Do the best you can to be balanced, but add opinions as necessary. Just be sure to label your opinions as opinions.
• I will generally point out things that should be improved or don’t work correctly in a product. Honest, respectful feedback improves products and helps buyers make informed decisions.Every developer I’ve ever met works really hard to create good products. If a problem exists, in almost all cases, they want to know about it and fix it. Developing good software and hardware these days is really, REALLY hard work. Bugs creep in unexpectedly and can’t always be caught before release.

SUMMARY

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.

---