Skip to main content Link Menu Expand (external link) Document Search Copy Copied
AK's Style Guide Template

Formatting and Organization

Table of contents

Guidelines for how to arrange and present the words you write.

Callout boxes

Callout types

Callout boxes (sometimes known as admonitions) are a great way to highlight important information or notices. There are three main types of callout boxes:

Note/Info: A useful (but not urgent) message. Notes often provide clarifying information, tips and tricks, or additional advice.

Caution/Careful: An important, semi-urgent message. Caution notes often invite the reader to slow down or tread carefully.

Warning/Danger: A critical, urgent message. Warning notes often contain information that will lead to a serious error if not followed; readers must heed this message at all costs.

Capitalization

Aperture Science branding

Make sure to properly capitalize Aperture Science’s product names.

For more information, see Aperture Science’s brand guidelines.

However, don’t capitalize the names of product features or processes unless the feature or process in question is a proper noun. (Rule of thumb: when in doubt, leave it lowercase.)

Code samples

Code formatting

Use code font for inline code samples, including method names and variable names, and code blocks for larger code samples.

  • Example: The isRaining variable can either be true or false.

Introduce code samples

Introduce code samples with a summary or description of what the code does. This introduction can end with a period or with a colon.

  • Example:
    The following sample shows how to activate your death ray at maximum strength:
    ` evilLair.deathRay(max_strength); `

For more information about including code samples in documentation, see APIs and SDKs.

Images and screenshots

Captions

Put captions and descriptions after their associated image.

If you’re including an image in procedural instructions, this means the image should appear first and its associated step (or steps) should appear afterwards.

When to use screenshots

Use screenshots sparingly. It can be helpful to include a screenshot when you’re describing how to navigate a user interface (or are describing the features of an interface), especially if the interface is too complicated to explain with words alone. However, don’t include a screenshot if a visual aid isn’t necessary.

This also means that procedural instructions may sometimes include screenshots, but not for every step. A single screenshot will often correspond to multiple steps.

In-text hyperlinks are a useful way to direct readers’ attention towards similar topics and related materials, especially if you don’t want to break the flow of a document to explain an important word or concept.

If you need to provide additional context for your readers, try linking to another post about that topic, a glossary entry that expands upon the definition of a term, or a guide with more detailed information about a specific parameter or object.

Descriptive link text

Use descriptive, non-obtrusive link text that doesn’t disrupt the flow of the sentence.
For example, to link to a doc called “Get Started With FraudSensor”:

  • No: To get started with FraudSensor (link), you’ll need to set up a detection tag.

  • Also no: To get started with Fraudsensor, you’ll need to set up a detection tag. Click here to learn more.

  • Yes: To get started with FraudSensor, you’ll need to set up a detection tag.

you’d like to link to another page that explains a specific term or concept, insert the hyperlink the first time that term or concept appears in the body of the doc (not counting titles or headings).

  • Example: The MediaGuard Dashboard includes data about IVT. Based on this MediaGuard data…

Lists

Introduce lists

Introduce lists with a summary or description of what the list is for. This introduction can end with a period or with a colon.

Ordered and unordered lists

When the order of list items isn’t important, use a bulleted (unordered) list.

  • Example:
    A bicycle has three main components:
    • Seat
    • Handlebars
    • Tires

When the order of list items is important, use a numbered (ordered) list. This usually appplies to sequences of steps or instructions.

  • Example:
    To bake a cake, follow these steps:
    1. Mix the batter.
    2. Bake in the oven.
    3. Decorate to perfection.

However, if a procedure only has one step, use a bulleted (unordered) list instead.

  • Example:
    To turn on the light:
    • Flip the light switch to the ON position.

Paired data

For lists that include two pieces of data per list item (like a glossary term and its definition), use a bulleted (unordered) list.

Format the first piece of data in bold, then use a colon to introduce the next piece of data.

  • Example:
    The theme park offers three attractions.
    • Screamin’ Mean Crazy Coaster: A high-speed roller coaster. Not recommended for children.
    • Big Joe’s River Adventure: A log ride with water features. Suitable for all ages, but riders will get wet.
    • Schubert Express: An interactive train tour. Perfect for young guests.

Parallel structure

Try to use parallel structure between different items in the same list. For example, you might start each list item with a verb or write each list item as a complete sentence.

To list or not to list?

If a list has fewer than three items, you might want to present the information in another format instead.

Procedural instructions

Imperative verbs

When possible, begin each step with an imperative verb. If a dependent clause precedes an independent clause, it’s okay if the imperative verb isn’t the first word in the sentence.

  • Example: Save your work before continuing.

  • Example: Choose any sword from the display case.

  • Example: To keep the park clean, pick up your trash.

Introduce procedures

Introduce procedural instructions with a summary or description of what the procedure are for and what the reader will accomplish. This introduction can end with a period or with a colon.

List all the steps

Use a numbered list to write out each step in a procedure. However, if a procedure only has one step, use a bulleted list instead.

For more information, see Ordered and unordered lists.

One action per step

Generally speaking, each step in a procedure should describe a single action.

However, sometimes it’s helpful to combine several fast, closely related actions into a single step, especially to describe UI navigation. You can use angle brackets to describe the process of navigating multiple menu items in a row.

  • Example: Select Filter > Distort > Liquify.

Tables

Introduce tables

Most tables need an introductory sentence (or paragraph) before the table begins. This introduction can end with a period or with a colon.

Table or list?

If a table only has two columns, you should probably format the information as a list instead.

Titles and headings

Title capitalization

Use title case for titles (h1).

Heading capitalization

Use sentence case for headings (h2, h3, and so on).

Include descriptions after every heading

Most docs can be improved by making sure that two headings never “touch.” Ideally, every section of a doc needs an introduction, so each heading should be followed by some kind of summary or description before the next subheading appears.
Try to provide necessary context for your reader: what is this section describing? Why is it important?

  • Example:
    ## Mammals
Mammals are warm-blooded vertebrates. They can live in water or on land.
### Aquatic mammals
Aquatic mammals are mammals that live primarily or entirely in water, including whales, dolphins, seals, and manatees. However, like all mammals, they still breathe air and must surface periodically to do so.

Heading hierarchy

Don’t jump between heading levels. For example, an h2 heading should not be immediately followed by an h4 heading.

Tasks in headings and titles

If a heading or title describes a task, use an infinitive (a “plain” verb) instead of a gerundive (an -ing verb).

  • No: ## Installing Java

  • Yes: ## Install Java

Miscellaneous

Avoid walls of text

Try to break up long stretches of text by adding subheadings, using bullet points, or splitting one long paragraph into several smaller paragraphs.

Consistency

Above all else, strive to be consistent across similar items in the same document. For example, if you’re writing a glossary, decide whether each definition should be a complete sentence or not. Don’t use complete sentences for search definitions and not others.

Spaces

Use one space after each sentence, not two.