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.
16 Responses to How I Write Technical Articles or Reviews
… 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??”
LOLOL Nailed it!
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?”
Thanks for all your careful thought and work to make things understandable! But can you please tell me where they moved my AOL?
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, thank you for your very kind words.
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.
I read this and realized it was a master class in writing in one concise article. Outstanding!
Jim & Robert:
Thanks for your very kind words. I’m glad you liked it.
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.
You are without any doubt the best instructor – both in person and written – I have ever come across on any subject. So many times the instructor seems to assume that the person he is instructing already knows much more than they do – as already described by others. All your tutorials are a model of clarity and you don’t leave out some crucial step that others so often do – on the assumption that it will be obvious to the reader. I thank you for all the help you have provided me over the years.
Thanks for your comments. I ALWAYS figure there’s someone reading my writing that knows more than I do – and looking for ways to point out what I missed.
Makes me extra careful checking my steps.
Wonderful to reread this article Larry, thanks for including it in your newsletter this week. With regard to content before or after an image, readers with low or no vision appreciate the context before they encounter the graphic so they may know what it’s for and digest it easier.
Again thanks for sharing this.
Larry, I’m a subscriber to MasterClass, which offers courses from a lot of top people in the filmmaking industry. I just sent them the following email to recommend you as an instructor:
“I’d like to recommend Larry Jordan (https://larryjordan.com/) as a MasterClass instructor in the category of video editing. Larry is a brilliant trainer, using both video and text tutorials. As a video editor myself, I’ve been an avid follower of Larry’s newsletters and webinars for about 15 years. With so many people now shooting their own films, there’s a need for a trainer who knows the ins and out of the hardware and software used for editing, as well as the art of editing itself. He would be an excellent addition to MasterClass.”
This is a truly lovely recommendation. Thank you!!
I’m very grateful – and very glad you like my work.
“I have been known to read a dictionary for its plot.”
That’s the Larry Jordan I love. Smart as all get out with the ability to make me laugh out loud. Thank you, my friend!
Grin. Glad you liked it.