AGENTS

Writing principles

• Be concise. People aren’t reading docs for fun; they want to achieve a goal. Cut all unnecessary words.
• Clarity over cleverness. Be simple, direct, and avoid jargon or complex sentence structure.
• Use active voice. Instead of saying “A configuration file should be created,” use “Create a configuration file.”
• Be skimmable. Use headlines to orient structure. Break up text-heavy paragraphs.
• Write in second person. Referring to your reader makes it feel like the documentation is written for them. ​

Common writing mistakes

• Don’t have spelling & grammar mistakes. “Grammatical errors may seem small, but they’re a key indicator of quality. They can degrade trust in your product as well.” —Brody Klapko, Technical Writer at Stash
• Avoid inconsistency in terminology. Calling something an “API key” in one paragraph then “API token” in the next makes it much more difficult for users.
• Consistency is key! You may not be complimented on your consistency, but people will absolutely notice and be frustrated by a lack thereof. - CT Smith, Head of Docs at Payabli
• Don’t use product-centric terminology. Your users don’t have the full context of your product (see “Know Your Audience”). Always orient language around the user’s familiarity with your product and what they’re trying to achieve.
• Avoid “Duh” documentation. Don’t tell users “Click Save to save.” Documentation should add value, not outline obvious steps.
• No colloquialisms. Especially for localization, colloquialisms hurt clarity.

Use bigger ideas, fewer words

Our modern design hinges on crisp minimalism. Shorter is always better. To learn more, see Brand voice.

Example Replace this: If you’re ready to purchase Office 365 for your organization, contact your Microsoft account representative.

With this: Ready to buy? Contact us.

Write like you speak

Write like you speak. Read your text aloud. Avoid jargon and overly complex or technical language. It should sound like a friendly conversation. To learn more, see Brand voice.

Example Replace this: Invalid ID

With this: You need an ID that looks like this: [e-mail]

Project friendliness

Use contractions: it’s, you’ll, you’re, we’re, let’s. To learn more, see Use contractions.

Example Replace this: To help you avoid traffic, remember anniversaries, and in general do more, Cortana needs to know what you are interested in, what is on your calendar, and who you are doing things with.

With this: To help you avoid traffic, remember anniversaries, and in general do more, Cortana needs to know what you’re interested in, what’s on your calendar, and who you’re doing things with.

Get to the point fast

Lead with what’s most important. Front-load keywords for scanning. Make customer choices and next steps obvious. To learn more, see Scannable content.

Example Replace this: Templates provide a starting point for creating new documents. A template can include the styles, formats, and page layouts you use frequently. Consider creating a template if you often use the same page layout and style for documents.

With this: Save time by creating a document template that includes the styles, formats, and page layouts you use most often. Then use the template whenever you create a new document.

Be brief

Give customers just enough information to make decisions confidently. Prune every excess word. To learn more, see Word choice.

Example Replace this: The Recommended Charts command on the Insert tab recommends charts that are likely to represent your data well. Use the command when you want to visually present data, and you’re not sure how to do it.

With this: Create a chart that’s just right for your data by using the Recommended Charts command on the Insert tab.

When in doubt, don’t capitalize

Default to sentence-style capitalization—capitalize only the first word of a heading or phrase and any proper nouns or names. Never Use Title Capitalization (Like This). Never Ever. To learn more, see Capitalization.

Examples Replace these: Find a Microsoft Partner Office 365 Customer Limited-Time Offer Join Us Online

With these: Find a Microsoft partner Office 365 customer Limited-time offer Join us online

Skip periods (and : ! ?)

Skip end punctuation on titles, headings, subheadings, UI titles, and items in a list that are three or fewer words. Save the periods for paragraphs and body copy. To learn more, see Punctuation, Headings, and Lists.

Example Replace this: Move a tile.

1. Press and hold the tile.

With this: Move a tile

1. Press and hold the tile.

Remember the last comma

In a list of three or more items, include a comma before the conjunction. (The comma that comes before the conjunction is known as the Oxford or serial comma.) To learn more, see Commas.

Example Replace this: Android, iOS and Windows

With this: Android, iOS, and Windows

Don’t be spacey

Use only one space after periods, question marks, and colons—and no spaces around dashes. To learn more, see Punctuation.

Example Replace this: Use pipelines — logical groups of activities — to consolidate activities that are part of a task.

With this: Use pipelines—logical groups of activities—to consolidate activities that are part of a task.

Revise weak writing

Most of the time, start each statement with a verb. Edit out you can and there is, there are, there were. To learn more, see Verbs and Word choice.

Example Replace this: You can access Office apps across your devices, and you get online file storage and sharing.

With this: Store files online, access them from all your devices, and share them with coworkers.