| name | microsoft-writing-style |
| description | Draft, rewrite, or audit friendly, concise product and technical UX content using an independently expressed reference-only interpretation of Microsoft writing guidance. Use for product help, setup, support, interface text, error messages, and technical content that should feel conversational, scannable, global, and action-oriented. |
Microsoft writing style
Help the reader act with a warm, practical voice and the fewest words that still
make the situation clear.
Protect the facts
- Preserve product behavior, names, UI labels, commands, code, versions, and limits.
- Do not promise a fix, outcome, security property, or availability that the source
material does not support.
- Keep legal and safety wording intact unless the user authorizes substantive review.
- Expose missing context instead of filling it with generic reassurance.
Put first things first
- Identify the reader's intent and current state.
- Lead with the result, action, or problem they care about.
- Add only the context needed to choose or complete the next step.
- Break complex comparisons into a list or table with parallel structure.
- End with a next action, result, or recovery path rather than a recap.
Use a helpful voice
- Address the reader as
you and use natural contractions when they improve flow.
- Choose familiar words and direct verbs. Keep technical terms when they are precise,
and explain them at first use.
- Prefer active voice. Name the app, service, or feature when it performs an action.
- Keep paragraphs short and vary sentence length only where meaning benefits.
- Use a calm, solution-oriented tone. Be more restrained for security, payment,
failure, and data-loss contexts.
- Write for global readers with literal language and explicit sentence structure.
Write product help and UI content
- Start procedures with the action and keep commentary outside the step sequence.
- Use verb-led labels that predict the result.
- Match visible UI wording and capitalization.
- For errors, state what did not happen, preserve any reassuring fact that is known,
and give a specific recovery action.
- Make the product take responsibility for product failures. Do not accuse the user.
- Use fragments only when the interface context supplies the missing grammar.
Avoid
- formal distance, corporate self-congratulation, and ceremonial introductions
- unnecessary jargon, abbreviations, noun strings, and abstract framing
- blaming language such as saying the user failed to perform an action
please in routine commands, difficulty judgments, and vague encouragement- long parenthetical asides and several clauses joined into one sentence
- jokes, excitement, or exclamation marks in stressful situations
- promises that support, security, or recovery will work without evidence
Final pass
Check that the important point appears first, the reader knows what to do, labels
match the product, sentences translate cleanly, and errors include an honest recovery.
Remove any sentence that says the content is about to help instead of helping.
Read references/provenance.md only for source,
attribution, licensing, or maintenance questions.
