Summary: The Scripting Editor, Dia Reeves, offers tips to help you improve your writing.

Microsoft Scripting Guy, Ed Wilson, is here. Today, I'm enlisting my editor, Dia Reeves, to help you write clear, concise, and consistent blog posts and feature documentation. Take it away Dia…

Hello to all of you who have lost your content team (or never had one) and have discovered that you are now writers! Gone are the days where PMs wrote specs, devs wrote code, technical writers documented how to use features, and editors made everything cohesive.

Let's hear it…group sighhhh…

Additionally, blog writing has become commonplace—and blogs most likely do not have the benefit of an edit pass. As much as I would love to edit every site I see, alas, I am a dying breed, and my services are hard to come by.

But what I can do is help you! Today I'm going to share some tips to help you improve your writing so you can get lots of positive comments about your blog posts and technical articles.

Make it friendly, but not too friendly

Slang is part of our everyday communication. But remember that, most likely, over 50% of your readers are non-native English speakers—and the whole world is not familiar with our English jargon. Using slang can make your writing difficult to understand, so if you want your readers to be engaged in your article, it's best to avoid it. Translation machines won't be helpful, and forget about getting accurate localization.

Use screenshots, but use them sparingly

We've all heard "a picture speaks a thousand words," but too many screenshots can interfere with the flow of your article. If a screenshot clarifies a confusing task, use it. If you choose a screenshot to show the Insert tab, you are wasting time and frustrating users who have to scroll through your article.

Ed saves a lot of time and avoids typing errors by effectively using screenshots to show Windows PowerShell commands and their output, for example:

Add boxes or arrows in your screenshot to quickly point out what you want the users to see. I like how this author assumed that the users could find Attach on the command bar, and he used the screenshot to highlight where to find the Attach empty disk command (which is somewhat hidden at the bottom of the screen):

Think single source

Single source means having one core document that describes a certain feature or function (for example, how to install an operating system). You then link to that core document anywhere you need to describe that feature or function, for example:

This article assumes that you have already installed your operating system. If not, see How to install Windows Server 2012 R2.

Why use a single source?

• A single source saves you time. Only one document needs to be maintained and updated, so the content stays fresh.
• The potential for errors is reduced because corrections are made only in the source document.
• There’s no confusion. A single source provides readers with a single good reference for accomplishing their task.
• The content in the core document has been verified.
• You don't have to worry about updating your instructions for every document!

Watch your voice

Decide which voice you want to speak in. When I was editing documentation for IT pros, the team used the second person (you). We wanted IT pros to know that we were providing actions for them to follow.

If you are writing a blog, the first person (I) is perfectly fine because you are speaking from your personal experience. It also indicates that you are taking responsibility for the text.

Ed offers this tip: "Stick with the second person if you are writing a team blog and its purpose is instructional—you need to do this, and then you need to do that. It is clean and simple."

Don’t confuse the reader by using several pronouns together, for example:

We can use the Clear-Disk cmdlet to erase the key, but I am going to target the disk number that is unique to the device you want to format.

This is better:

I can use the Clear-Disk cmdlet to erase the key, but I am going to target the disk number that is unique to the device I want to format.

Be kind to your readers

People who come to your site are busy. They want the information delivered quickly and clearly. If you enter scholarly mode and use a lot of run-on sentences, your readers are gone with a quick click. Here is a great example:

Over the past couple of decades, machine learning has become a key driver of information technology, and therefore, a central, albeit often hidden, part of our everyday lives, and it can be used to continuously improve our online search results, optimize the content and advertising that we see, online and offline, improve the efficiency of our cars while we drive, and tag our loved ones in our vast collection of digital photos.

Phew…I don't know about you, but my brain turned off after the fourth comma.

Make it easy for your readers by using short sentences, simple language, and bulleted lists whenever possible. Here is how I would suggest that the writer present that information:

      Over the past couple of decades, machine learning has become a key driver of information technology. We can use
      machine learning to:

• Improve online search results
• Optimize the content and advertising that we see online and offline
• Improve the efficiency of our cars while we drive
• Tag people in our vast collection of digital photos

Notice how all the bullets start with a verb? That is called parallelism, and you want it. Using all verbs or all nouns is an easy way to develop parallelism in bulleted lists and headings.

Ditch the spec speak

I know. You have a great spec. When the time comes to document your new feature for the world to use, you can simply reuse that spec text. Right?

Well, wrong. By the time you are explaining a feature to others, you need to be telling them how to use it. Don’t waste time telling them what they already know—anticipate what they need to know.

Here is some beautiful spec talk:

The Contoso supersmart mouse will run on two AA batteries.

But this is not helpful to people who have already purchased the mouse and want to use it. They probably found your article because they couldn’t find how to insert the batteries. Users need something more like this:

Insert two AA batteries into your Contoso supersmart mouse by pressing the red dot on the underside of the mouse…

Stay in the present tense. Any time you see the word "will" in your document, you are probably not out of spec speak yet.

Be a good teammate

Editors provide a high-level overview of a documentation set or blog series for a team, and they ensure that articles written by different writers use consistent terminology.

You are a professional and you want your team's documentation to be cohesive, right? To be a good teammate means that you use style guides. If you are creating articles for Microsoft sites, here is your reference: Microsoft style guides. If you don't work for Microsoft, your manager or legal representative should know where your style guide is located.

Watch acronym usage

Much like slang, acronyms have a habit of sneaking in to our vocabulary and documentation. Your team may have affectionately adopted an acronym for a feature, but your readers won't have a clue what it means.

The proper way to represent an acronym is to spell it out on the first mention with the acronym in parentheses, for example:

• infrastructure as a service (IaaS)
• Active Directory Domain Services (AD DS)

Style guides and legal sites have information about properly using acronyms. At Microsoft, you can find approved acronyms in Term Studio.

Ask someone to read it

Writing and editing require different mindsets. When I am writing, I am focused on presenting my content and developing a nice flow in my article. When I am editing, I am focused on technical and grammatical details. I am also absorbed in the overall organization of the article and how it fits with other articles in a documentation set.  

If you don't have editing support, it is important to ask someone to read your writing before you publish it. It’s a good idea to create a system for peer reviews. This is especially important for writers who are non-native English speakers—try to find native English speakers to review your writing.

If you are a reviewer, dig in! Offer suggestions. You aren't doing readers any favors by glancing at an article and commenting, "Looks good, buddy."

To show how easy it is to publish mistakes in text, I'm going to tattle on myself…

In my first ever blog post, The Scripting Editor Tells All, I wrote:

…it needs to be clear, concise, and consistent. And guess what? Those are the three tenants of good editing!

Do you see it?

I didn't—I read past it because I was in writing mode. None of the four people I asked to read it before I posted it noticed it. Spellcheck missed it because it is not a misspelled word. When my article went live, my son pointed out that I had used "tenants" when I really meant "tenets."

Yep. That was embarrassing.

~Dia

Thanks, Dia. I'm sure many writers learned something today.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy