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.

Callout frequency

Don’t use an excessive number of callout boxes in a single document, and try not to use two callout boxes consecutively with no intervening text between them (if you can avoid it).

Keep callouts short

Try not to use callout boxes that contain long walls of text.

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.

One way to write descriptive links is to use link text that’s similar to the title of the link destination or provides additional information about the page you’re linking to.

If you include the exact title of a page, match the capitalization of that title.

  • Example: Follow the steps outlined in Getting Started With FraudSensor before proceeding.

If you don’t include the exact title of a page, capitalize the link text as if it were part of a normal sentence.

  • Example: Make sure you’ve installed FraudSensor before proceeding.

However, if it’s too hard to seamlessly integrate a link into a sentence, you can also write a new, complete sentence that directs readers towards a relevant topic. These sentences should typically begin with a phrase like “For more information,” or “To learn more about [topic],” before including the link.

  • Example: For more information, consult our FraudSensor Parameters guide.

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.

Numbers

When to spell out numbers

Spell out numbers zero through nine when they appear in a sentence, unless a numeral would be more appropriate (like for a version number, file size, or percentage).

  • Example: A bass guitar can have four, five, or six strings.

  • Example: Files should not exceed 8 MB in size.

However, if another numeral appears in the same sentence, use numerals consistently throughout.

  • Example: Of the dentists surveyed, only 1 in 100 recommended using chocolate frosting instead of toothpaste.

Use numerals for numbers 10 and higher.

  • Example: There were 14 penguins at the zoo.

If an ordinal number appears in a sentence (like first, third, or twenty-ninth), spell it out.

  • Example: The seventh page contains information about your warranty.

Spell out indefinite and nonspecific numbers.

  • Example: Millions of people suffer from seasonal allergies.

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.

Location

If a step requires the reader to perform an action from a specific page, menu, or location, state the location before you describe the action.

  • Example: Using the Country drop-down menu, select your country of residence.

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.

Outcomes first

In most situations, if a step includes its intended outcome or goal, describe the outcome of the step before you describe the instructions to carry it out. (In other words, the dependent clause comes first.)

  • No: Select New file to create a new file.

  • Yes: To create a new file, select New file.

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.