Writing style guide

What is a writing style guide?#

A writing style guide, also known as a manual of style, is a document containing standards (rules) for writing and formatting documents. Its purpose is to assist writers in maintaining consistency in their writing style and ensuring that the documentation is clear and easy to understand.

Whether crafting a blog article or collaborating with a documentation team, a style guide is crucial in maintaining a consistent brand voice and tone. Without this consistency in your writing style, your readers may struggle to grasp your intended message.

For instance, observe how the Google Developers documentation style guide utilizes its guide to maintain consistency.

In the following example, you’ll see clear guidelines on formatting lists. They not only provide clear guidelines but also examples on representing various list types in their documentation and how to introduce them.

How to create a writing style guide#

If you’re unable to find a pre-existing guide that aligns with your company’s style and brand, consider creating an in-house guide.

This allows you to tailor the guide to effectively communicate your company’s values, establish a desired voice and tone, and ensure the use of appropriate grammar and punctuation.

In this section, you’ll delve into these essential aspects and more for creating a comprehensive style guide.

The following are important attributes that must be contained in your style guide:

• Establishing the Company’s Brand

  The initial step in crafting an effective guide involves aligning the writer’s mindset with the company’s identity, values, and objectives.

  This step is crucial as it enables the writer to comprehend the company’s brand and how to effectively communicate it to the reader.

  Addressing a company’s brand entails emphasizing its values, mission, and vision. Placing your company’s brand identity at the forefront of your style guide is essential, serving as a constant reminder for the writer.

  An excellent illustration of effective brand communication is demonstrated by Slack. They clearly outline their identity, values and all they represent.

  

  Figure 1. Slack’s brand identity

  While a solo writer may find this step less critical, it becomes crucial when collaborating with a team of writers. Ensuring everyone is aligned with the company’s brand fosters consistency in communication.

• Utilize an Existing Publishing Guide

  While you embark on creating your own guide, it’s worth remembering that guides have a rich history, and there’s no need to reinvent the wheel. Consider using an existing publishing guide as a starting point for crafting your own.

  Choose a guide that aligns with your specific requirements. For instance, if you’re working on technical documentation, opt for a APA Style guide. If you’re crafting an academic document, consider using the MLA handbook.

• Voice and Tone

  Understanding voice and tone is crucial, yet it can be misunderstood by many writers. Voice represents the personality of your writing, while tone sets the mood.

  Voice and Tone tip

  If you’re composing a blog post about a new product, aim for a friendly voice and an excited tone.

  For companies with diverse social media outlets for customer communication, maintaining a consistent voice and tone is essential. This consistency plays a key role in building trust with customers.

  When determining the tone and voice for your company, consider asking a few key questions:

  • Are you aiming to be formal or informal?
  • Do you prefer a friendly or professional tone?
  • Is your style more serious or humorous?

  Answering these questions will guide you in making decisions about the tone and voice that best represent your company.

  An exemplary case of a company effectively communicating its voice and tone is Mailchimp. They provide extensive details on how their company engages with customers.

  

  Figure 2. Mailchimps voice and tone

• Grammar and Punctuation

  Having defined the voice and tone, it’s now time to delve into the finer details of your guide. Consistent rules regarding grammar and punctuation are essential; otherwise, your documentation may become confusing for your readers.

  When determining the grammar and punctuation rules for your company, consider asking a few questions:

  • Do you want to use the Oxford comma?
  • Are you inclined towards the serial comma?
  • Is the em dash or en dash your preference?

  Given the multitude of standards in this area, refer to Shopify’s style guide for a comprehensive example. They provide clear explanations with numerous examples to illustrate their grammar and punctuation rules.

  

  Figure 3. Shopify’s grammar and punctuation

  In your guide, be sure to provide examples for every point you make. This practice aids your writers in understanding the intended message and application of the guidelines.

• Formatting

  While many guides combine the formatting and grammar sections, I’ve chosen to separate them due to their distinct nature. Formatting pertains to how you present content to your readers. Consider questions like whether to use bold or italics, headings or subheadings, lists or tables, etc.

  When establishing formatting rules for your company, pose key questions to guide your decisions;

  • Do you prefer using bold or italics for emphasis?
  • What is your approach to using headings or subheadings?
  • Are lists or tables the preferred format?

  Asking these questions will aid in defining the formatting style for your documentation.

  A notable example of effective documentation formatting can be found in the Google Developer Documentation Style Guide. This guide provides comprehensive rules for formatting, covering areas such as headings, titles, numbers, lists, tables, and more.

  

  Figure 4. Google Developer Documentation Style Guide formatting section

• Terminology and abbreviations

  To create the terminology and abbreviations section, compile a comprehensive list of all terms and abbreviations specific to your company. This list guides writers in using the correct terms and abbreviations in documentation.

  When deciding on terminology and abbreviations, consider key questions:

  • Should two-letter initialisms have periods?
  • How do you introduce abbreviations?
  • What significance do italics and abbreviations hold for your company?

  Answering these questions aids in making informed decisions for your style guide.

  A commendable example of incorporating terminology and abbreviations into documentation can be found in The 18F Content Guide. This guide provides insights into when to use abbreviations, how to introduce them, and more.

  

  Figure 5. 18F’s Content Guide terminology and abbreviations section

• Images and diagrams

  While many companies have a separate design style guide for visuals and media content, it’s crucial to include essential information on how writers source images.

  Certain questions need answers if writers are responsible for creating images or diagrams. For instance:

  • What is the preferred image format?
  • Are there specific preferred dimensions?
  • Should all images include a brand logo?

  Addressing these questions will provide clarity for writers creating visual content.

  Providing guidance on producing images aligned with the company’s goals is essential for writers. DigitalOcean serves as an excellent example, effectively communicating necessary information about incorporating images into content.

  

  Figure 6. DigitalOcean’s image and assets style guide section

Utilize a Template#

If you prefer not to start from scratch or are on a tight deadline to create a company style guide, consider using a template.

Templates serve as boilerplate guides where you can input your company’s information, including vision, mission, and all the necessary sections discussed above.

While a quick Google search yields several style guide templates, Writers.com offers a particularly neat and recommended template.

Downloading this template provides a solid starting point for creating your style guide.

Always keep in mind that consistency is the key to a good style guide. Adhere consistently to the standards and rules you adopt.

Why is it important for technical writers to have a writing style guide?#

The primary aim of a style guide is to enhance communication between the writer and the reader. With a well-defined style guide, writers can uphold consistency throughout their documents, thereby reducing the cognitive load on readers.

Below are few reasons why adopting a style guide is beneficial:

• Establishing a distinct brand representation: Take popular blogs like MDN or DigitalOcean, for instance. You can quickly identify an article as theirs simply by observing the writing style. This is made possible by their adherence to a style guide, ensuring a consistent brand voice and tone.

  MDN Writing Style Guide Sample

  How to add images and media

  To add an image to a document, add your image file to the document’s folder, and then reference the image from within the document’s index.md file using Markdown image syntax or the equivalent HTML element.

  To learn more about MDN writing style guide, visit MDN Web Docs.

  This is crucial as it contributes to building trust with your readers. When readers trust you, they are more inclined to return for more content. This is particularly significant for technical writers aiming to establish a brand or companies seeking to cultivate a community around their product.

• Minimize readers’ cognitive load: A style guide enables you to sustain consistency in your writing style, simplifying the understanding of your documentation for readers. Without a style guide, readers would need to invest more time deciphering your documentation due to inconsistency of content.

  The longer it takes for readers to comprehend your documentation, the higher the likelihood they’ll leave. This is detrimental for your blog or company, as it translates to potential loss of subscribers or customers.

• Simplified editing process: A style guide streamlines the editing of your documentation for your editors. With a clear set of guidelines, they know exactly what to look for during the editing process. Without a style guide, editors would spend more time figuring out what needs editing.

  The longer editors spend searching for useful information to edit your documentation, the greater the chance of making mistakes. These errors can have significant repercussions on the credibility of your documentation.

• Single Source of Truth (SSOT): It serves as a centralized point of reference containing all information related to your documentation. SSOT encompasses grammar and punctuation rules, formatting guidelines, terminologies, abbreviations, as well as visual elements like images and diagrams.

  The lack of a style guide means that your writers will invest more time figuring out how to format their documents. This is due to the absence of a trustworthy source containing all the necessary information for editing their documentation.

Popular style guides and how to pick one for your project#

While you can create your own style guide (which we’ll discuss later), there are advantages to relying on an existing guide.

Using an existing style guide saves time since you don’t have to create one from scratch; you can simply choose one that fits your needs and start using it immediately.

Style guides are categorized based on the type of content they address. Examples include style guides for technical documentation, academic writing, open source documentation, and more.

Here are details about some of the most popular style guides, aiding you in selecting the one suitable for your project.

1. Publishing style guides#

Publishing style guides are employed by publishers to uphold consistency in their publications. They encompass aspects such as grammar, punctuation, formatting, and more. Here are details about some of the most popular publishing style guides:

• The Chicago Manual of Style
• The Associated Press Stylebook
• The MLA Style Manual
• The APA Style Guide

2. Technical writing style guides#

Technical writing style guides assist technical writers in ensuring consistency in their documentation. They address aspects like punctuation, terminology, abbreviations, images, diagrams, and more. Here are details about some of the most popular technical writing style guides:

• Microsoft Manual of Style
• Google Developer Documentation Style Guide
• Apple Style Guide
• IBM Style Guide

3. Content style guides#

Many blogs and companies utilize concise style guides to uphold consistency in their content. These guides cover various aspects to ensure uniformity. Here are details about some of the most popular content style guides:

• MDN Web Docs
• DigitalOcean
• The Red Hat Style Guide
• The Mailchimp Content Style Guide

4. Open source style guides#

Guides governing technical content in open source projects are crucial for maintaining consistency. Here are details about some of the most popular open source style guides:

• Gnome Documentation Style Guide
• Open SUSE Documentation Style Guide

5. Government and Academic style guides#

Government agencies and academic institutions rely on style guides to uphold consistency in their content. Here are details about some of the most popular government and academic style guides:

• Princeton University Style Guide
• Gov.uk Style Guide
• Plainlanguage.gov

Answer the following questions.