Five Things to Check in Microsoft Style
The Microsoft Writing Style Guide is the go-to style for information technology (IT)–specific communications. The IT audience is large and varied, ranging from help desk staff to chief technology officers. The people that make up that audience come from all over the world and speak many different languages.
Microsoft’s style helps you develop content that is concise, straightforward, and culturally sensitive, whether you’re writing an application user interface (UI), developing a website, assembling a knowledge base article, or creating a conference presentation.
Here are five takeaways from the Microsoft Writing Style Guide to help you create outstanding IT content.
Keep It Concise, Conversational, and Friendly
Write it like you’d speak it (within reason, of course). Contracted verb forms (it’s, you’re, let’s) are perfectly acceptable. Use a friendly, conversational tone, and get to the point quickly.
As Microsoft says, “Write short headings, short sentences, and short paragraphs.” If you’re working on a long document, be sure to include navigation so your audience can find what they need quickly.
Most of your IT audience will find the information they need through a search, so be mindful of important keywords, and “front-load” those words in your sentences. For example, instead of this:
“To help create consistent documents, use the templates built into Microsoft Word.”
use this:
“Templates in Microsoft Word help you create consistent documents.”
Your job as an IT communicator is to give your readers or viewers the information they need to answer a question or make a decision. Tight, concise sentences that avoid overlong explanations project confidence and reduce the risk of misinterpretation.
Make Sentence Capitalization Your Default
At PerfectIt, we use title case for headings (as you can see). However, Microsoft style never uses title capitalization for headings, titles, captions, run-in headings, or UI labels. In fact, Microsoft’s default style is to reserve capitalization for the first word in a sentence and proper nouns (including product and feature names).
If, however, your particular project has settled on title caps for headings, Microsoft prefers capitalizing:
Prepositions of five or more letters (unless a preposition is the first or last word).
Adverbs (including too).
The first word of labels in UIs and application programming interfaces (unless the word is always lowercase, such as fdisk).
Watch Those Acronyms
The IT audience is overloaded with acronyms and abbreviations. It’s easy to fall into the acronym “trap” and assume that your audience knows what you mean. Certainly, some acronyms are better known than their spell-outs (e.g., USB, FAQ, URL). For lesser known acronyms and abbreviations, however, balance their use against the need for clarity and recognizability among your audience.
Microsoft provides the following guidelines for acronym use in writing for IT audiences:
Machine-translated content. Use acronyms with caution in content that is likely to be translated by machine, such as artificial intelligence (AI)–based closed captioning services. Such AI algorithm can easily confuse an acronym with a common word (e.g., RAM [computer memory] and ram [a male sheep]).
Possessive acronyms. Microsoft style avoids making acronyms possessive unless they refer to a person or organization (e.g., CEO).
Microsoft product names. Do not create abbreviations by shortening Microsoft product names (e.g., Configuration Manager, never Config Manager or Config Man). To date, the only acronym Microsoft Legal has approved for a product name is ATP (for Advanced Threat Protection).
Acronyms in the dictionary. If you’re unsure of an acronym, first check the A–Z word list in the Microsoft Writing Style Guide. Another good source is The American Heritage Dictionary (Microsoft’s preferred dictionary).
A or an before acronyms. Whether you use a or an before an acronym depends on whether the word is pronounced with a leading vowel sound (e.g., an FTP port, an MTU setting) or a leading consonant sound (e.g., a SQL query, with “SQL” pronounced “sequel,” not “ESS-QUE-ELL”).
Acronyms in headings. Avoid introducing acronyms in titles and headings unless they improve search engine optimization.
Use Bias-Free Language
There are several key points in Microsoft’s approach to bias-free communication:
Standardize on second person (you) whenever possible.
Avoid slang (slang tends not to translate well into other languages).
Avoid stereotypes in names and job roles.
Use gender-neutral terms.
Wherever possible, rewrite sentences to avoid gender bias. For example, use plural nouns and pronouns to avoid having to use he or she. Similarly, you can refer to the person’s role rather than the person.
Avoid using words that have racial, political, or military associations.
Here are a few examples of words to avoid and suggestions for their replacement:
|
Instead of |
Consider this |
|
chairman |
chair |
|
manpower |
staff |
|
manmade |
synthetic |
|
master/slave |
primary/subordinate |
|
demilitarized zone |
perimeter network |
|
hang |
stop responding |
|
kill |
stop, end |
|
execute |
run |
|
I know her |
I know that manager |
|
hacker |
attacker, cybercriminal, malicious hacker |
Write Outstanding Procedures
Good procedures—the how-to steps common in help articles—are a cornerstone of IT communication. Follow these tenets to write clear procedures:
Discrete Actions
Make each step a discrete action (although it’s OK to combine short steps if the actions are performed in the same part of the UI).
Include a Direction
Include a direction that finalizes the action (e.g., “Select Today, and then select Apply.”)
Use Complete Sentences
Use complete sentences that start with or include an imperative (e.g., “On the ribbon, select the Review.”)
Limit Procedures
Limit procedures to seven steps. Where a task requires more steps, use separate procedures grouped under topical headings—for example:
To save a document
From the File menu, select Save.
In the dialog box, in Save As, type a name for the document.
Select Save.
Is It a Single Step?
If a procedure consists of a single step, replace the number with a bullet—for example:
To open a new document
– From the File menu, select New Document.
Use PerfectIt to Streamline Your Work
When you’re creating content for an IT audience, you’re inherently making a complex topic easier to understand.
Why not make your work easier by using an automated consistency checker like PerfectIt?
Using PerfectIt is like having your own secret quality control department. It handles the nitty-gritty details of the editorial process so that you can focus on creating easy-to-read documentation.
When you run PerfectIt on your work, it will:
Check abbreviations. PerfectIt reconciles the use of acronyms across your document with the click of a button. You’ll know that all the acronyms used in your document—from AI to PaaS to VUI—are defined on first use.
Check inconsistent capitalization. PerfectIt will alert you if you’ve used Recordset in one place and RecordSet in another and let you choose the correct treatment.
Check heading case. Microsoft style uses sentence case for headings, and you can set PerfectIt to enforce that.
Check inconsistent hyphenation. PerfectIt will also scan your copy and warn you if you’ve hyphenated words inconsistently. Did you type clickstream in one place and click-stream in another? PerfectIt will flag inconsistencies like this—even if they’re hundreds of pages apart.
Check figure numbering. User guides tend to be full of screenshots. PerfectIt helps to ensure that all figures are labeled and that they appear in consecutive order.
Check IT-specific terminology. You can add preferred terms to PerfectIt’s checking, such as opcode, p-code, Wi-Fi, parent/child, and W3C.
Check for product and brand names. You can add important names like Microsoft .NET, SharePoint, and Oculus Rift to your preferred styles so that PerfectIt flags variations such as .net, Sharepoint, and Oculus Riff.
Make sure biased language doesn’t creep in. PerfectIt can check for terms you want to avoid, such as master/slave or demilitarized zone.
If you use the Microsoft Writing Style Guide, PerfectIt is the secret weapon you need to get all Microsoft’s style points exactly right. When it comes to their most important documents, Microsoft writers even use PerfectIt themselves.
Let PerfectIt take care of these details so that you can focus on your mission: creating IT documents that are clear, helpful, and easy to read. Click to get a free trial.