Style guides

Style guides define rules for using language in a given context.

These rules provide a “common voice” that customers recognize and expect when working with professional content.

A good style guide improves your writing and overall effectiveness.

Recommended guides

For technical docs, consider adopting one of the following:

• Google developer doc style guide
• Microsoft Writing Style Guide

Each guide was developed by the publisher using research and customer focus groups. Each is actively tested, reviewed, and maintained by their respective organizations.

Adopting either guide helps you create better docs.

For best results, adopt one as your primary resource and use others as supplements. This leads to more informed editorial decisions, especially when trying to decide whether it’s time break the rules.

Other style guides

Other guides exist, including:

• Apple Style Guide
• Red Hat Technical Writing Style Guide
• Salesforce Style Guide for Documentation and User Interface Text
• Ubuntu: Canonical Documentation Style Guide

This discussion focuses mainly on editorial style guides.

The term style guide can also refer to:

• Design style guides, also known as visual style guides, which describe interface design and the use of visual controls.

  Examples include:

  • Google Material Design guidelines
  • Apple Human Interface Guidelines
    
    

• Branding style guides, which companies use to present consistent messages to consumers and to protect their brand names, trade dress, and trademarks.

• Project style guides define “house rules” for projects and organizations.

  These generally describe exceptions to other resources and generally reflect specific decisions made by the editorial team.

  If you’re new to a team, consider asking whether there is a project style guide–even when familiar with the primary style guide.

More editorial resources

When your style guide doesn’t answer a particular question, consider these resources:

1. Merriam-Webster (modern spelling, usage, and thesaurus)
2. Oxford English Dictionary (legacy language, archaic terms, and alternate uses)
3. The Chicago Manual of Style (book or subscription)
4. The Elements of Style, by William Strunk & E.B. White (Fourth edition available at Internet Archive)
5. Purdue University Online Writing Lab (OWL)
6. National Archives (NARA) Principles of Clear Writing

Historical guidelines

Modern technical writing style is based on plain language, a set of guidelines originally developed for the Plain Writing Act of 2010.

These guidelines emphasize brief, clear docs with direct language. See Voice & tone to learn more.

Earlier approaches include:

• Simplified Technical English (STE), a set of standards originating in the aerospace industry during the 1980s.

  STE was designed to reduce confusion, especially among readers who did not understand English as a native language.

  Many guidelines assumed that technology would never be able to accurately translate content in real time.

  STE writing rules were designed to minimize confusion. Because many languages do not support contractions, for example, STE forbade their use.

  As a result, content written to STE guidelines can seem formal, stiff, and stilted (especially to modern ears).

• Microsoft Manual of Style (MMOS)

  Based in part on STE, the MMOS was considered a primary resource for technical publications at Microsoft for more than two decades.

  Early versions were called the Microsoft Manual of Style for Technical Publications (MSTP).

  Microsoft invested heavily in technical writing as a discipline, which helped MSTP become a standard resource for other technical writing teams.

  In 2018, MMOS was superseded (replaced) by the Microsoft Writing Style Guide.

Vital statistics

• 12 May 2024: Updated and reworked for current standards
• 15 June 2017: Updated and expanded
• First post: 29 Jan 2017