Technical Writer Style Guide Examples
A technical writer style guide contains the necessary style and formatting guidelines to develop consistent technical content that helps customers understand the product.
Many organizations have publicly available technical writing style guides. In this article, we’ll share a curated list of technical writing style guide examples, allowing technical writers to better understand the various components of technical style guides.
What is a Technical Writer Style Guide?
A technical writer style guide is a comprehensive technical document containing style, formatting, grammar, and punctuation rules for technical writers to develop engaging technical content.
A technical writing style guide informs the technical writers about the standard brand language, tone, terminologies, abbreviations, document structuring, and other writing best practices. It contains various examples and templates for every type of content.
Style guides like AP Stylebook or Chicago Manual of Style serve as a solid foundation of style and formatting for technical writers. A summary of the AP Stylebook is found here. Most technical writing style guide examples shared in the next section are based on these foundational guides.
10 Technical Writing Style Guide Examples
Technical writers aim to generate high-quality, engaging content and technical writing style guides empower them to do so. This is why we have curated a list of 10 prominent technical writer style guide examples below.
1. Google Developer Documentation Style Guide
The Google style guide contains editorial guidelines for writing Google-related technical documentation. These guidelines are curated based on ease of understanding, accessibility, localization, and globalization.
Google developer documentation style guide has the following major sections:
General principles
Highlights principles such as writing friendly, respectful, and conversational documentation for a global audience to promote inclusivity without making unsupported claims or disclosing upcoming features, avoiding third-party sources, and using jargon meticulously.
Language and grammar rules
This section includes guidelines for the use of capitalization, language articles, prepositions, active voice, abbreviations, tenses, pronouns, and more.
Punctuation
Includes editorial style guide for using commas, hyphens, colons, parentheses, periods, etc.
Formatting and organization
Lists down rules for adding phone numbers, dates, figures, footnotes, units of measurement, spaces, and more.
Linking
Highlights how external sources can be added to the technical documentation. This includes guidelines for cross-references, URLs to images, link text, and headings as links.
Computer interfaces
This section includes rules for adding API reference code, code samples, code in text, command-line syntax, and UI element reference in the technical documentation.
HTML and CSS
Includes HTML and CSS formatting guidelines, along with fonts and font size conventions.
Names and naming
Contains guidelines for adding personally identifiable information such as domain names, email addresses, etc. It also includes rules for writing filenames and trademark terms.
Additionally, Google recommends two external style guides to improve the understanding of technical writers related to technical documentation editorial style. These include the Red Hat supplementary style guide for product documentation and the Apple style guide (which we will discuss next).
2. Apple Style Guide
Apple style guide enables technical writers to organize and format the following Apple-related materials:
- Instructional material
- Technical documentation
- Reference information
- Training programs
- User interfaces
The Apple style guide contains editorial guidelines related to Apple terminology and writing style to help developers, writers, and editors maintain a consistent tone in Apple materials. The style guide has the following major sections:
Style and usage
This section contains the usage format for specific numbers and key terms used at Apple.
Writing inclusively
Like Google, Apple guide also encourages writers to promote diversity and inclusivity in their content. For instance, avoiding any oppressive and violent words, idioms, and stereotypes, avoiding the use of colors to portray positive and negative attributes, using diverse sets of names and locations that cover all ethnicities and backgrounds, and using gender-neutral pronouns, etc.
Units of measure
Includes rules and examples for writing units, symbols, prefixes, and abbreviations.
Technical notation
Includes style and usage guidelines for code and syntax, particularly for developer documentation.
International style
This section contains general guidelines for writing country names, country codes, currency codes, language codes, dates and times, telephone numbers, and more.
The Apple style guide offers comprehensive guidelines for writing technical documentation for any product. It can be adopted and optimized by technical writers within their organizations.
3. Microsoft Writing Style Guide
Microsoft writing style guide is one of the few comprehensive technical writing guides that offer guidelines for all types of technical writing, including documentation, apps, websites, or whitepapers for Microsoft and non-Microsoft materials. This guide highlights Microsoft’s customer-centric conversational tone, which is crisp and clear, warm and relaxed, and aimed at offering help to customers.
The Microsoft writing style guide includes many sections. Like the previous two style guides, it also stresses the importance of accessibility, diversity, and inclusiveness. For instance, instead of using a word like “mankind,” use “humanity” or “people.” Similarly, use the word “workforce” instead of “manpower.” The guide calls it bias-free communication.
An interesting section of this guide includes guidelines about writing content for chatbots and virtual agents. Bots have become an essential part of the customer service and customer success pipeline. Due to their frequent interaction with humans, Microsoft offers many recommendations to conform virtual agents and chatbots to human-like communication standards.
Microsoft style guide goes into much greater detail for writing technical content. The guidelines include comprehensive sections on content planning and design planning. It also contains sections related to grammar, punctuation, text formatting, word choice, acronyms, capitalization, and responsive and scannable text.
4. IBM Style Guide
IBM press released a 300+ page IBM style guide for writers and editors back in 2011. It contains ten major sections, including grammar, punctuation, formatting, structure, references, numbers, interfaces, glossaries, indexes, and diversity. However, the IBM style guide is not freely available, but a 44-page sample is available here.
Meant for IBMers in particular and developers in general, IBM offers two online style guides as well, i.e., IBM Design Language and IBM Developer Experience Guide.
IBM Design Language offers principles and guidelines to craft unique designs and rich experiences. It includes guidelines, examples, and tutorials for many design and visual components, including:
- Typography
- Color
- Grid
- IBM logos and iconography
- Illustration
- Photography
- Data visualization
- Layouts
- Infographics
- Animations
IBM Developer Experience Guide portrays the practical design philosophy of IBM. It contains guidelines and themes for building an IBM Developer brand. It includes two major sections: Brand and Implementation.
The brand section contains guidelines for creating, designing, and selecting logos, typography, color schemes, pictograms, and illustrations, while the implementation section discusses how design is applied to digital channels, events, and merchandise.
5. DigitalOcean Technical Writing Guidelines
DigitalOcean offers a single-page technical writing guideline document divided into three main sections:
- Style
- Structure
- Formatting and Terminology.
This guide mainly focuses on writing technical articles, including procedural tutorials, conceptual articles, and task or solution-specific articles. It presents an outline structure for these articles and details what each section would include and look like.
The DigitalOcean technical writing guidelines include various formats and examples for adding code snippets to the technical content. DigitalOcean stresses that technical information should be written for all experience levels. It should be practical, friendly, and technically accurate.
Additionally, the guide dives deep into the nitty-gritty of technical content writing for DigitalOcean. Writers who want to publish their content on DigitalOcean must adhere to these guidelines. It talks about standardized terminologies, IP addresses, URLs, and DigitalOcean-specific information. Writers must also follow the technical best practices guide to develop high-quality, consistent content.
6. Mailchimp Content Style Guide
Mailchimp content style guide is a goldmine of style and formatting guidelines for technical writers. This guide is available for anyone to use and adapt according to their requirements, subject to Mailchimp attribution.
Mailchimp promotes content that is empowering, respectful, truthful, and educational. The style guide contains the following major sections:
Grammar and mechanics
This section provides specific guidelines for the use of abbreviations, acronyms, active voice, capitalization, emojis, numbers, dates, decimals, percentages, currency, telephone numbers, and more.
Write educational content
At Mailchimp, there are various types of educational content, including help center articles, video tutorials, webinars, Instagram reels, API documentation, release notes, and training materials. Mailchimp offers general guidelines for such educational content like staying relevant to the topic, keeping the headlines short, providing context, and proper formatting. Non-Mailchimp users can adapt these guidelines to their educational resources.
Write legal content
Legal content requires accuracy, clarity, and succinctness. Legal documents generally include copyright policy, API use policy, acceptance use policy, terms of use, and the very important privacy policy. Mailchimp content style guide addresses all formatting issues related to legal content.
Write email newsletters
Email newsletters have become an effective form of marketing. Companies send newsletters for product or feature announcements, alerts, invitations, and industry tips. Mailchimp offers guidelines for writing an effective email newsletter by addressing each component, including name, subject line, preheader text, body, call to action, and footer.
Write for social media
Mailchimp provides style guidelines for publishing content on social media channels like Facebook, Instagram, Twitter, and LinkedIn.
Accessibility
Like all major style guides, Mailchimp promotes diversity in technical writing. Writers are given specific guidelines to consider readers of all mental and physical capacities. Guidelines include writing direct and scannable content, using headers and hierarchy, using alt text and closed captions, and more.
Copyright and trademarks
Copyright applies to every type of content. This section highlights the correct usage of copyrighted or trademarked content.
Moreover, Mailchimp promotes an informal, straightforward, and positive tone with a dry sense of subtle and appropriate humor rather than being forced or snobbish.
7. Atlassian Design System
The Atlassian design system is another online comprehensive guide covering different aspects of the Atlassian brand, foundations, components, patterns, and content. The content section contains specific guidelines for writing Atlassian content. It is divided into six categories:
Inclusive language
Atlassian strongly advocates for words free from discrimination, prejudice, or stereotype. They have identified eight categories and explained each with examples, where words should be used cautiously. These include culture and religion, race and ethnicity, ableism, vulgar language, sexism, sexual orientation and gender identity, ageism, and socio-economic status.
Language and grammar
This section covers all formatting guidelines for all writing components, including abbreviations, active voice, capitalization, dashes, numbers, dates, etc.
Vocabulary
This section clarifies how certain words and terminologies are used at Atlassian.
Voice and tone principles
Atlassian intends to use its voice and tone to inform, empower, encourage, motivate, satisfy, and delight readers to build trust, inspire action, and deliver pleasing experiences. Each of these language emotions and moods is accompanied by examples.
Writing guidelines
This section contains best practices for writing product messages, such as error messages, success messages, info and warning messages, and feature discovery.
Writing style
Atlassian wants its technical information to be bold, optimistic, and practical.
The remaining sections of this design system are also worth looking at. Although the design system is intended for Atlassian products, it can be adapted externally.
8. Shopify Polaris
Polaris is Shopify’s design system built to develop great user experiences. Just like the Atlassian design system, it contains guides for content, design, components, and patterns. Let’s discuss the major sections of content guidelines in detail.
Voice and tone
This section lists the guidelines to maintain Shopify’s voice and tone across technical content. The tone must be real, proactive, and dynamic. It should guide and teach the Shopify merchants to help them succeed. The guide shares numerous examples of how the tone can be adapted according to the situation.
Accessible and inclusive language
Creating inclusive content is a core aspect of the Shopify Polaris style guide. They have shared numerous examples of how certain words should be used. For instance, instead of using the word “handicap,” use “disability.” Similarly, using “wild” or “outrageous” instead of using “insane” or “crazy.” The guide also disallows the use of racist or gender-biased language.
Grammar and mechanics
Like previous style guides, this section discusses guidelines for various writing components such as capitalization, punctuation, addresses, dates, headings, spellings, etc.
Naming
This section shares guidelines for naming various products offered by Shopify. Names should be thoughtful, descriptive, or evocative. The guide share numerous examples for each category.
Actionable language
This section encourages writers to design actionable content that allows merchants to get things done. For instance, it talks about how buttons and headings should be named that encourage action. It also differentiates the use of different words and their impact, e.g., select vs. choose or edit vs. manage.
Product content
By following product content guidelines and tips, Shopify merchants can build a rich user experience. These tips include using plain language, writing short sentences, avoiding idioms, encouraging action using call-to-action buttons, and being consistent in language.
Help documentation
Help documentation educate and empower merchants about various components of an app or integration. This section highlights many guidelines and relevant examples for writing effective help documentation.
Merchant-to-customer content
Merchant-to-customer content is available on checkout pages, shipping update emails, digital receipts, POS screens, etc. It represents the merchants’ voice and tone towards their customers. Polaris provides various guidelines and examples to represent such content.
9. Salesforce Style Guide for Documentation and User Interface Text
This guide is mainly targeted toward customer-facing documentation and user interface text. The manual has two major sections: Style A-Z and Glossary.
The Style A-Z section includes all style guide components in alphabetical order. Most subsections are accompanied by examples. However, the format and structure of the guide take some getting used to. Once the writers are familiar with the style guide, they can write professional, high-quality, and consistent text using it.
The glossary section defines all the terminologies used across Salesforce documentation and user interface in alphabetical order.
Like the Atlassian design system and Shopify Polaris, Salesforce offers Lightning Design System to allow developers and designers to create consistent user interfaces. This system enables designers to build interfaces based on four core principles: clarity, efficiency, consistency, and beauty. Some major components include platforms, accessibility, component blueprints, design tokens, icons, and utilities.
10. SUSE Documentation Style Guide
SUSE is another significant mention in this list because it is an open-source style guide that can be adapted to your requirements. It provides guidelines and best practices for writing SUSE documentation.
The SUSE documentation style guide includes many important sections: language, structure, formatting XML, working with AsciiDoc, documentation content, etc. It is a single-page HTML document, so all guidelines are available in one place. It offers many examples and conventions for writing technical documentation. Thanks to community contributors, open-source style guides improve over time.
Now that we have discussed some technical writing style guide examples, let’s briefly talk about the various technical documents that can be written using these style guides.
What Type of Content Can be Written by Using Technical Writer Style Guides?
Not all style guides are the same. And not all are meant to work for each type of technical material. Depending on technical content requirements, organizations can either develop their technical style guides from scratch or adapt a mixture of existing guides.
Following are the types of technical documents that can be written using technical writing style guides:
- Business proposals/Sales proposals/Funding proposals: A document meant to win over potential clients and their investments must be accurate in style and formatting. The technical information written in business/sales proposals must adhere to standard technical writing guidelines to sell products and services to potential clients.
- Marketing proposals/Promotional brochures/Advertisements: Good style and formatting build a solid foundation for marketing and advertisement projects.
- Training/Technical support guides/User manuals: Style guides make technical user manuals and support guides easy to read.
- Information booklets: Like user manuals, the technical writing in information booklets should be scannable.
- Product prototype documents: Because the prototype can have incomplete features, the supporting documentation must clearly mention what the users should expect from the prototype.
- Software development guides: Software documentation makes or breaks software in the real world.
- Catalogs: A catalog must be carefully curated as it contains important information about a product.
- Press releases: Mistakes in press releases can damage a company’s reputation. A press release should pass all style and formatting guidelines before making it public.
What Are the Key Benefits of Using Technical Writing Style Guides?
A technical writer aims to write technical documentation and related resources in high quality. However, most technical writers find it difficult because technical materials can be very lengthy. For instance, software documentation or API documentation may span over 100 pages. A style guide makes the job of a technical writer a bit easier.
Let’s look at some benefits of using technical writing style guides:
Saves Time
A technical writer saves a lot of time while writing technical documents by using a style guide. It is a single source of truth that contains all of the company’s style and formatting guidelines.
A document that incorporates a style guide accurately saves time for the end-user as well. For instance, high-quality software documentation saves developers a ton of time finding the correct information.
Moreover, a style guide makes technical editing easier as well. Editors can use it as a reference guide to update technical materials. Disputes between writers and editors are minimized.
Brings Consistency
Today, an organization’s technical content is shared across multiple channels to reach a wider audience. If the content produced is not consistent across all platforms, customers may find it displeasing. A style guide brings brand consistency in terms of voice and tone. It ensures that the consumers will be presented with consistent brand messaging regardless of the platform.
Improves Technical Communication
Technical communication includes documentation and design. It can be internal or external. In either case, the relevant technical information should deliver the intended message. A style guide contains guidelines for writing both internal and external technical documents. For instance, writing internal emails regarding product or feature updates. If the email does not conform to the company’s terminologies, the team may not interpret the email accurately.
Concluding Note
A technical writing style guide contains guidelines, tips, and best practices for writing short, simple, and precise technical information. We have summarized some notable technical writer style guide examples above. They allow technical writers to curate technical content with confidence. You can either use these existing style guides or adapt them according to your needs. Moreover, you can create your own style guide as per your requirements.
Remember, a style guide facilitates technical writers rather than limiting their writing capabilities.
“Break any of these rules sooner than say anything outright barbarous.”—George Orwell, Politics and the English Language
