Post History

Source: https://writers.stackexchange.com/a/34596
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/34596
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

There have been significant changes in technical communication style over the last 20 years, and particularly in the last five years as increasing volumes of evidence have shown that simple friendly language is both easier to understand and more respected by users.

But it sounds like your supervisor is a stickler and the way you convince a stickler is by citing an authoritative source. So here is that source. There are few works on technical communication style that are better established or more respected than the Microsoft Manual of Style. That manual has recently undergone a major update to bring it into line with modern practice and research. You can find it on line here: [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/)

Here are the top ten tips from that guide (see the guide for details and examples of each tip):

> Use bigger ideas, fewer words: Our modern design hinges on crisp minimalism. Shorter is always better.
> 
> Write like you speak: Read your text aloud. Does it sound like something a real person would say? Be friendly and conversational.
> 
> Project friendliness: Use contractions: it’s, you’ll, you’re, we’re, let’s.
> 
> Get to the point fast: Lead with what’s most important. Front-load keywords for scanning. Make customer choices and next steps obvious.
> 
> Be brief: Give customers just enough information to make decisions confidently.
> 
> 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.
> 
> Skip periods (and : ! ?): Skip end punctuation on titles, headings, subheads, UI titles, and items in a list that are three or fewer words. Save the periods for paragraphs and body copy.
> 
> Remember the last comma: In a list of three or more items, include a comma before the conjunction.
> 
> Don’t be spacey: Use only one space after periods, question marks, and colons—and no spaces around dashes.
> 
> Revise weak writing: Most of the time, start each statement with a verb. Edit out you can and there is, there are, there were.

Original score: 9