How I Write Technical Articles or Reviews

Posted on by Larry

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:

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:

FORMAT

The Structure

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.

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

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.


9 Responses to How I Write Technical Articles or Reviews

  1. Karsten Schlüter says:

    Excellent, Larry!

    … now, same for VIDEO-tutorials. Probably hard to get that into 5…
    • no “whazzup!”-yelling at the beginning (except you’re Andrew Kramer)
    • “write a script and for heavens sake use it”
    • no law forces you to record in a single shot, editing is allowed
    • “keep that crazy mouse still!!!!”
    • and when you record yourself: “What’s that in the background? a kitchen sink??”

    😉

  2. Warren Nelson says:

    Exactly, Larry!

    I cut my teeth doing customer support where the opening exchange usually went like this. . .

    “Ok, open your browser and we’ll get this figured out!”

    “. . . . . . What’s a browser?”

    “It’s you program you use when you want to work on the internet. Just open that.”

    “OH! You mean my AOL! Why didn’t you say that?”

    “Cool! Now, in the address bar, type thi. . . .”

    (Interrupting) “What address bar?”

    sigh

    Thanks for all your careful thought and work to make things understandable! But can you please tell me where they moved my AOL?

  3. Constance Beutel says:

    Larry,
    For me, you are the epitomy of excellent training and instruction. Whether it is your articles or your videos, you explain what you will cover, you break it into ‘chapters’ that allow easy access and reference and you provide both the technical depth and practical applications through clear demonstrations….AND you do it with authentic interest and engagement!
    I think you’re brilliant! . . . And I’m sticking to that assessment.
    Cheers and thank you,
    Constance

  4. Robert Withers says:

    Larry,
    Thank you for writing a superb article about writing that goes beyond the topic more broadly to web writing and journalism in general

    This should be a key reference for anyone learning about technical writing and other non-fiction writing.

    (You also hit on a pet peeve and cliche of contemporary journalism: undefined acronyms! There’s a highly respected, decades-old, high-brow magazine that causes me to frequently leaf backwards in articles to try to find what a repeated acronym stands for.)

    Your carefulness with communication makes your training invaluable and enlightening.
    All best,
    Robert

  5. Jim B. says:

    I read this and realized it was a master class in writing in one concise article. Outstanding!

  6. Mark Johnson says:

    I agree with Constance. You are one of the best educators I’ve come across, either in-person or on-line. Your lessons are always clear and clean. All of the information, without the rabbit trails.
    One of the things that amazes me most is how you are able to address questions, without hearing them being asked. I can’t tell you how many times I’ve watched one of your webinars or lessons and said to myself, “Wait a minute, how does that . . . ?” and within a few seconds, you cover it. Its like you’re able to read my mind.
    Thanks so much for posting the communication tips in this article.

Leave a Reply

Your email address will not be published. Required fields are marked *

Larry Recommends

Final Cut Pro X 10.4

FCPX Complete

Edit smarter with Larry’s brand-new webinars, all available in our store.

Access over 1,900 on-demand video editing courses. Become a member of our Video Training Library today!

JOIN NOW

Subscribe to Larry's FREE weekly newsletter and save 10%
on your first purchase.