Professional Writing Hints from a 20-Year Technical Writer

Although many of you know me as “that guy that writes a lot”, I am not a natural great writer. I’ll never write the great American novel. But professionally writing for over 20 years, including 12 books and probably nearly 2,000 individual articles, have helped to hone my average talent over the years. I couldn’t help but get better just from sheer volume alone. Here are the hints I would share to anyone wanting to write technical articles.

Start Paying Attention to What You Like With Other Writers

One of the single best things you can do is to start to cognitively realize what types of writing you like to read. What authors and writers do you like to read and why? Before I was an author, I barely paid attention to who the author of an article was, unless they had a picture next to their name. After writing for a while, I started to notice when I lost track of time while reading a piece of good technical writing, where I was excited to read it all the way to the end in one sitting. Most articles I find myself skipping and jumping ahead, trying to find the most salient points. But the good authors hooked me early on and gave me so much useful information that I read every word and bookmarked their articles.

Become the writer you want to be by noticing who writes well for what you like to read. After a while, you’ll catch yourself looking for the author’s name before you read something to see if it is someone you recognize. Think about what it is that they do…the way they write…that you enjoy. And then try to mimic that component in your writing.

Get Your Grammar and Spelling Down

I’m not so great at this, but if you’re going to write for a living, it helps to know the difference between ‘there’, ‘their’, and ‘they are’, ‘it’s’ versus ‘its’, when to use ‘which’ versus ‘than’, and ‘more’ versus ‘bigger’. It can’t hurt to understand what an Oxford comma is and what side of the issue you fall on. You’ve got to know where to put your commas, understand subject-verb agreement, and get rid of dangling modifiers. Spelling counts and word processors are notorious for not catching errors.

Learn How to Write Structurally

Early on, I just started writing what was foremost in my head and let the piece naturally develop while I was writing it. And that still happens today. But I’m far more likely to take a few minutes before I start writing and plan out the piece. Every article has to have a beginning, middle, and end. Begin with an introduction and end with a summary. There are still many times where what I’m writing turns into something else completely different than what I started out writing, but it always has structure.

Grab With a Hook

One of the best writing hints I ever learned was to make the title of the article and the first sentence exciting enough that you catch people’s attention. Most technical reading is decided by a person reading the title. Be too boring there and you’ve lost 90% of your potential audience. Of the people who decided to read your article, perhaps another 75% make a decision after the first few sentences of the article. That’s the most you’ve got – title plus a sentence or two – to hook readers. Make the most of it. Go around to different magazines and websites and figure out what titles made you want to read something. What sentences hooked you so you wanted to read more? Why? What was it about those titles and sentences that interested you?

Note: For some strange reason, titles with a number, such as “8 Ways to…” are read more than articles without numbers in them. Think about it, Cosmopolitan magazine loves doing “57 Ways to Please Your Boyfriend” articles for a reason. Popular Mechanics loves doing “7 Ways to Turn Your Car Into a Hotrod!” The publishers of my articles can tell you the ones with numbers in the titles often did better. I’m not sure why, but don’t argue against Cosmopolitan magazine. It’s been around since 1886 and out-survived nearly every other magazine. They must know something.

Get a Good Editor

If you’re like me…and challenged in all things grammar and spelling…get yourself a great editor. A great editor is worth their weight in gold. If faced with a nice editor that catches some of your mistakes and a mean editor that sometimes hurts your feelings, but catches all your mistakes, go with the mean editor. Don’t let your feelings get hurt just because an editor is correcting your writing. You might even disagree with what the editor is saying, but most of the time, they are seeing something that needs to be fixed.

When I was writing my first book, for O’Reilly, and handed in my first chapter draft, the editor said, “I thought you said you could write. This looks like you took this from a PowerPoint presentation. It’s terrible.” I was upset, but he was right. I had taken it directly from a PowerPoint presentation I did on the subject. After I got over being offended, I started improving my writing style. I’ve thanked the “mean” editor many times since.

With that said, as you get better at writing and you “find your voice”, don’t let editors steal your voice. Sometimes, especially early on, your writing style can be crappy and needs to be fixed or get heavy upgrades. But decades into writing, I’ve come to love editors who can fix my spelling and grammar errors without completely replacing my writing style with the way they would have written it. Get a good editor who finds your mistakes and makes suggestions without replacing your voice.

Spell out All Acronyms on First Use

Our world is full of acronyms. In general, spell them out on first use, with the abbreviation in parentheses following. It’s Internet Protocol (IP) addresses not IP addresses. It’s Transport Control Protocol (TCP) ports not TCP ports.

Only the absolutely most understood, ubiquitous, abbreviations, like TV and PC, should be used without first explaining them. Also, use the full name of any vendor or their product upon first use. It’s Microsoft Corporation not Microsoft. It’s Microsoft Word not Word.

Learn and Use a Style Guide

Most publications follow a selected “style guide” which guides the editors in how to treat certain subjects and words. It helps with, Is it: “e-mail or email”, “Internet or internet”, or “spear phishing or spearphishing”? Many writers follow “AP Style”. You can learn more about it here: https://en.wikipedia.org/wiki/AP_Stylebook. The whole AP Stylebook costs money, but you can find much of it for free on the Internet. Read it and memorize what you can to save yourself and your editor time.

Never Publish Your First Draft

No matter how great you think your first draft is, rarely is as great as you believe. Almost all of the greatest writers write draft after draft. What you might think is writing gold can usually be improved by a second reading. For my most important writing, I often let it sit a day or two, to let it leave my mind a bit, and then come back to read it with “fresh” eyes. Send your second draft, or the draft you feel comfortable with to your editor.

Write About What You Know

This isn’t usually a hard one to figure out. You shouldn’t be writing about something that you don’t know well, unless your article is simply quoting other experts. Once you get the first few articles under your belt, it can be tempting not to turn down any topic that gets sent your way. Heck, my career was made by accepting pieces on subjects that I knew little about. But most of the time, even if I knew nothing, by the time I wrote the article, I knew a lot about the subject. Sometimes I took the subject explicitly because I didn’t know a lot about a subject and wanted to know a lot more (i.e., my quantum book is a great example).

The trick is to talk to experts in the field when you aren’t an expert. Don’t be afraid to ask newbie questions. The smartest people in the fields I was investigating were also the ones who loved to teach the most about the subject. If there is a secret to my success, I was never too afraid to ask “dumb questions”. I figured if I didn’t know the answers, there were plenty of other people, including in my audience, who didn’t know either.

Confirm Quotes

If you quote someone and don’t have it recorded or aren’t taking from someone else’s writing, get the quoted person to confirm the quote. One of the biggest complaints I’ve heard from people quoted in any article anywhere is that they were quoted wrong or out of context. I’ve made a habit of getting everyone I’m quoting in an article to confirm their quote.

A few times, I’ve had people tell me they wish I didn’t include a particular quote in an article. Maybe they think it might put them in a bad light or have them insulting other people they didn’t want to diminish. I’m not with the NY Times or National Enquirer. I’m not trying to make enemies. Put someone in a good light with a quote and you can usually use them as a source for the rest of your career.

Try Something at Least Once Before Recommending It

This is one of the most important recommendations ever given to me by a guy who wrote dozens of the most popular technical books (Mark Minasi). He told every author he knew, “Try it once before you write about it!” He was so, so right. Do not trust what you read from other people and then write about it like it’s the gospel. You will get embarrassed if you do so at some point in your career. I remember once being yelled out by a subject matter expert because I had written something wrong. I replied, “I got it from the instruction manual that you wrote!” He yelled back, “It was wrong!”

I can’t tell you how many times I’ve tried something that didn’t work even close to how easy or well it was said to have worked by someone else. If you try it, you will almost always learn some small points that you can pass along to your readers that will make you appear as if you were the expert, when all you did was try it once.

Never Assume Your Audience Knows Anything

About every eight presentations I do, someone comes up to me at the end and sheepishly asks, “What did you mean by patching?” They know they should already know what it means because everyone else in the audience obviously nodded in approval when I told them to, “Patch their computers in a timely manner.” But they didn’t know. When writing, explain the basics…quickly, if you have to; before moving onto more sophisticated topics. Your writing will improve because you do it. Readers will like you more.

Note: Like the acronym advice, only skip the basics if you are sure that 99.9% of your audience doesn’t need an explanation (like for the word Internet) or if it just isn’t that relevant to the article. For example, I don’t explain the words modem or router unless I’m writing an article explicitly about modems or routers.

A Picture Is Worth a Thousand Words

The saying that a picture is worth a thousand words is true. When you’re writing technical articles and you have the ability, do the words plus the picture. Not only do pictures teach using another angle and reinforce the material, but it breaks up the text. In long articles, people like breaks. I should have included a picture here.

Make sure if you use anyone else’s picture that you have permission to do so. Most pictures on the Internet are not free to use. Just because it’s on the Internet, does not mean it is free to use.

Respect copyrights, trademarks, and cite where you got things from. Wikipedia’s common use licenses allows borrowing and you can find free to use pictures all over the Internet, but they MUST BE EXPLICITLY MARKED AS FREE TO USE.

Get Your Picture Published With the Article If Possible

This is another great Mark Minasi hint. If possible, get your picture published with any writing you do. It will make you instantly more recognized and more people will look for your writing and follow it. Early on, if I had a choice between getting paid a small amount of money or having my picture published alongside my article, I’d take the picture. A picture is worth a thousand words. A picture of you starts to establish a brand. If you can get paid and have your picture alongside the article, that’s even better.

How to Get Article Ideas

I’m good at turning my regular life into topics for articles. Here’s a few ideas on how to generate topics for articles:

If you find yourself writing a paragraph explanation back to someone in an email, that might be an article. People often ask me where I get all my ideas. After all, I’ve written nearly 2,000 public articles. Many of them just began as long replies back to people who asked me a question. If I found myself typing back multiple paragraphs to someone, I always asked myself, “Could this be an article?” Many times, the answer was yes.

 If You Find Yourself Wondering How Something Works, That Might Be an Article

Many times, I found myself wondering about something that someone else DIDN’T explain so clearly in their article or video. Those questions often bugged me enough that I just had to find out more about the subject and answer it myself. Sometimes I found out that the author of the article or video really didn’t understand something as well as they thought they did. When you find yourself trying to answer a question, oftentimes, that makes a good article. You’re usually not alone.

If You Notice a New Trend, You Might Have an Article

Many of my articles have been written based on observations of growing trends. Many times, many other people have noticed the same trend…something happening a second time…but instead of waiting for it to happen the third time…I decided to research more about it, and learned it was a developing global trend I could write about.

Keep a Notepad Handy

After 20 years of writing, including a weekly column for nearly 15 years, sometimes my writing ideas did not always come easily. Some weeks and months, I struggled to think of a single topic and what I thought of did not excite me. Other times, I would wake up from a dream or a light sleep and have five good ideas in my head. I always sleep with a notepad beside my bed to write down good ideas. When I’m awake, I type (or voice record) them down into my computer or cell phone to send topics to myself, but I find opening up a cell phone or iPad device makes it harder for me to get back to sleep versus just writing something down. Most of my best ideas have come in a moment when I wasn’t even thinking of how to think of a new writing topic. The best ideas just appear to you as if sent by some higher power. Be prepared for those moments.

Document Your Writings

Lastly, I’m good at writing down every URL link where one of my writings has been posted. It helps for resume time. It helps to give links to people who are asking questions you thoroughly answered in a previous article. And it helps to shut down people who think, “He couldn’t possibly have written nearly 2,000 articles! He must be exaggerating.”

Well that’s it. These are the hints I wish someone had told me at the very beginning. I’m still learning to write better every day. And thanks to the editor of this article who fixed all my typos and grammar errors, I’m better today than I was yesterday. Feel free to send any questions my way: [email protected] or [email protected].