←Back to Portfolio

The Style Guide

Introduction

Structure & Formatting

Language & Grammar

Accessibility Concerns

For Non-Native
English Speakers

Resources

Structure & Formatting

Don’t underestimate how you structure and format your articles and other documentation—they can make your internal documentation easier to read, interact with, and contribute to.

Capitalizations

Use Title Case to capitalize page titles and Sentence Case to capitalize other headline articles.

• Title Case: “Generalized Style Guide for Technical Documentation”
• Sentence Case: “Generalized style guide for technical documentation”

Bold and Italics

For documentation to be readable, the content can’t just be a wall of text. Along with the other sections under Structure and Formatting, using bold and italics in technical writing can help draw attention to important information. They help make the information scan-able.

• Use italics to indicate the title of another publication.
• Use bold text to highlight an “Example” or “Note“

Contractions

Contractions are okay to use in internal documentation; they make the docs sound more informal and friendly.

Emoji

Emoji can help present a more informal tone as well, but they should be used sparingly. They can sometimes distract the eye, in particular for folks with visual processing disorders.

Lists

Lists are great for organizing information and a great way to break content up and increase overall readability. Sometimes, using headlines and paragraphs would work better.

If everything on a page is a list, then nothing is. It’s harder for readers to scan an article for those important steps if the whole article is a list.

Some general recommendations:

1. Use lists when you have several related items—for example, a list of steps in a process or product features.
2. If the items in the list are concise (just a word or phrase), a list may be best, but if the items in the list are longer and more complex, it may be better to give the information in paragraph form.
3. If the information you present has a clear hierarchy or structure, it may be more effective to use a numbered list.
4. Make sure that the list serves a clear purpose in your document.

Headings and Subheadings

Headings and subheadings are important for organizing and structuring your content. They can also make your content easier to read and understand. Used correctly, they provide a hierarchical breakdown of the document, which can visually guide a reader (and browsers or screen readers).

Some tips for using them effectively

• Headings should be clear and concise and accurately reflect the content of the section they introduce.
• Use heading levels consistently, with main headings at Level 1 and subheadings at subsequent levels.

Using Images, Video and other Media

Images, videos, and other media should be used to illustrate important concepts, make articles easier to read and break down ideas more engagingly.

[Depending on where the documents live, you might add best practices on how they are linked or embedded here.]

Best practices:

• Use descriptive alt text for images to make documents more accessible to users with visual impairments.
• Use appropriate file formats and optimized sizes so they load quickly and are accessible to all users
• Get permission to use elements from external sources (yes, even when using internally)
• Don’t substitute for written explanations. Instead, use images and other elements to increase accessibility and understanding.
• Choose appropriate visual aids for the information you are presenting.
  • For example, a GIF might be a good choice for demonstrating a specific action, while an image might be more effective for showing the layout of a user interface.

Image Sizes

[Use this section with the specific information needed depending on where your images and videos are being displayed.]

References and Other Links

[Some additional information and context can go here based on where your documents will live and company preferences.]

• Use hyperlinks to provide extra information or to reference external sources. [Questions to consider: Does the company have any policy regarding linking out to other sites? A list of authoritative sites depending on the subject?]
• Use descriptive link text rather than generic text like “click here” for links.
• Avoid too many hyperlinks in an article because it can make the text difficult to read.