Formatting and Organization

Table of contents

• Capitalization
  • Aperture Science branding
    
• Images and screenshots
  • Captions
    
• Links
  • Helpful hyperlinks
    
  • Descriptive link text
    
  • Link the first instance
    
• Numbers
  • When to spell out numbers
    
• Titles and headings
  • Title capitalization
    
  • Heading capitalization
    
  • Heading hierarchy
    
• Miscellaneous
  • Avoid walls of text
    
  • Consistency
  • Spaces

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

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.)

Images and screenshots

Captions

Put captions and descriptions after their associated image.

Links

Helpful hyperlinks

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.

Link the first instance

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…

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.

Titles and headings

Title capitalization

Use title case for titles (h1).

Heading capitalization

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

Heading hierarchy

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

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.