Writing With Style: 10 Style Guides to Inspire You
A writing style guide is a set of rules and agreements for everyone involved in writing or editing documentation in a company. Usually, a style guide prescribes using certain words, expressions, terms, and punctuation. It can sometimes go even beyond that and cover content architecture or UI texts.
What are the main benefits of following a style guide?
- It will be a single point of truth to keep the documentation consistent even when it’s written by a team of writers, each with their own personal writing style.
- It alleviates the editors’ workload coming from external contributors.
- A style guide brings an anonymous authority into the writing process and prevents conflicts.
Do you need to create your own style guide?
Most writing teams rely on several recognized style guides: The Chicago Manual of Style, Microsoft Style Guide, or Google developer documentation style guide. Sometimes companies need to cover cases specific to their industry or business. But even in this case, you can save time and effort basing it on an established style guide.
Let’s look at ten great style guide examples.
The UK Government
The UK Government Digital Service style guide covers grammar and spelling conventions for all content under gov.uk and is a fine example of the signature British writing style. It also has a special COVID-19 section that describes how to communicate on this sensitive topic.
Mailchimp
The Mailchimp Content Style Guide contains guidelines for all who write content, including documentation, emails, and even legal agreements. It includes tone of voice, grammar, style, and accessibility recommendations.
RedHat
The RedHat style guide contains not only grammar and style guidelines, but recommendations for the correct markup elements usage. It also describes the appropriate language to use, for example, to avoid slang, neologisms, ambiguity, and anthropomorphism.
Atlassian
The Atlassian Design guide contains a content section as well. It covers best practices and patterns for both documentation and conversational writing and provides a lot of detail on inclusive writing.
Apple
A classic example of a software documentation style guide. It covers a wide range of the writing rules, like how to use terms, units of measurement, numbers, and so on.
A nice practice to swipe from Apple’s style guide is to have a history of changes so that users can check when the specific rule was introduced.
Adobe
Adobe, in general leans, on the Associated Press writing standards and their guide is a set of exceptions from it. They also have separate sections dedicated to writing about errors and new user onboarding.
18F
There is a government related style guide from 18F, which is the US General Services Administration (GSA) internal team who provide digital services for the US government. Their guide is user-centric since the government often addresses a broader audience. The style guide helps users understand what they are saying and keeps them from being wrongly interpreted. A separate section is dedicated to inclusive language.
GitLab
The GitLab style guide is not only about grammar and style, but about the principles and content architecture they follow. This style guide is used by both the GitLab writers and external contributors.
It contains guidelines about the topic types they use, documentation-first methodology, markup elements usage, document’s structure, proper directory organization, and much more. It references other recognized technical style guides, like Google and Microsoft, as a primary source of truth.
SUSE
The SUSE style guide focuses on the document’s purpose and proper structure, but also covers language guidelines, terms and definitions usage, and markup reference. It’s most interesting feature is that it starts with a separate section about how to define your target audience.
AListApart
Last but not least, is the A List Apart style guide, which is an example of the reader-first approach. It not only describes how to write and style texts in a clear and concise manner, but also how to treat visual assets. An interesting feature is it describes how and when it is appropriate to use metaphors.
What will you choose?
Mind, there is no one-size-fits-all when it comes to language and style. So there are two options here:
- Check which rules and recommendations in other style guides you studied do not suit your case and create exceptions.
- Check what rules are missing and create ones from scratch.
Are there other options? Share!
UPD: Use style guides right inside your IDE
Want to check your writing against some recognized industry style guides? Try Grazie Professional.
Grazie Professional is a plugin that works in any IntelliJ-based IDE. Install it on top of the Grazie plugin which is bundled with most IntelliJ-based IDEs. If it’s not, you need to add Grazie first.
Out of the box, Grazie Professional offers three popular style guides:
- Microsoft Writing Style Guide
- Google Developer Documentation Style Guide
- alex linter rules for inconsiderate writing
Open Settings | Editor | Natural Languages | Grammar and Style | Rules and select the rules you want to apply. Switch rules on and off, mix and match them as you need. Just make sure you haven’t checked the same or conflicting rules in different style guides, as they can clash.
You can also define your project-specific style guide with custom rules and replacements. All to help you maintain a consistent and professional voice across the docs.
Subscribe to On Writer's Side Blog updates
