AH Technology style guide

This guide lies down some rules for creating a uniform writing style.
Using a uniform writing style offers several benefits, supported by extensive research:

Enhances clarity and readability
A consistent style makes documents easier to understand and follow, reducing ambiguity and the chance of misinterpretation. Research shows improved writing can increase usability by up to 124%.

Improves professionalism and brand identity
Uniformity projects a professional image and reinforces brand consistency across all company communications.

Increases efficiency
Writers can create content more quickly by following established guidelines, and readers can find information faster due to predictable structure and language. Studies demonstrate productivity gains of up to 37% with clear writing.

Simplifies collaboration and maintenance
When multiple authors contribute, a common style ensures coherence and makes documents easier to update and maintain over time.

Facilitates translation and localization
Consistent terminology and sentence structure simplify the process of translating documents for global audiences.

Reduces learning curve
New employees can more easily understand and absorb information when it's presented in a familiar and consistent format.

Enables enterprise scalability
Style guides allow organizations to maintain consistency across large, distributed teams and global operations. Both Google and Microsoft demonstrate how comprehensive style guides support thousands of contributors while maintaining quality and coherence.

Aligns with industry standards
Following established patterns used by leading technology companies ensures compatibility with widely adopted practices.

Headings and structure

Heading style

Use sentence-style heading capitalization.
Only capitalize the first letter, this is easier on the eye as the heading reads as a normal sentences. Markup or styling makes a heading stand out, no need for extra capitalization.
Standard capitalization rules still apply for names, brands, weekdays, etc.

Correct: "Capitalization in heading style"
Incorrect: "Capitalization in Heading Style"

Note: if this rule fires because of an unknown name, add the name to the vocabulary file.

Heading punctuation

Don't end headings with punctuation marks such as periods, question marks, or exclamation points. Headings should be concise and clear without trailing punctuation.

Correct: "Heading punctuation"
Incorrect: "Heading punctuation."

Sentence structure

Active voice

Using an active voice helps in clearly conveying the message.

A shorter and more clear message makes it easier to understand. Fixing this error often entails rewriting the sentence.

Correct (active voice): "Set the boolean to true"
Incorrect (passive voice): "The boolean must be set to true"

Accessibility considerations

Not everyone speaks English natively. Write short and easy sentences using common words, making it easier to understand.

Splitting up long sentences into shorter ones can help with readability.

Word choice and terminology

Colons

Text that follows a colon should be in lowercase, unless it's a proper noun or acronym.

Correct: "Remember this rule: always use lowercase after colons."
Correct: "The system supports three formats: JSON, XML, and YAML."
Incorrect: "The system supports three formats: Json, Xml, and Yaml."

Contractions

Use contractions to make the text more conversational and approachable.
For example: "don't" instead of "do not", "it's" instead of "it is", "you're" instead of "you are".

Date format

Use the ISO 8601 date format (for example, YYYY-MM-DD), not:
31.07.2016 or 31/07/2016 or 31 July 2016, or July 31, 2016.

Correct: "2016-07-31" or "2025-05-26"
Incorrect: "31.07.2016," "31/07/2016," "July 31, 2016," or "31 July 2016"

First person

Avoid using first-person pronouns like "I", "we", or "you" in documentation.
Instead, use third-person language to maintain a neutral and objective tone.
For example: "The system allows users to configure settings" instead of "You can configure settings in the system."

Future tense

Avoid using future tense in documentation, as it can create confusion about when actions will take place.
Instead, use present tense to describe current functionality or past tense for completed actions.
For example: "The system supports multiple languages" instead of "The system will support multiple languages."

Inclusivity

Use inclusive language to ensure that documentation is accessible and respectful to all readers.

Examples:

  • Use "team," "folks," or "everyone" instead of "guys"
  • Use "staffed," "operated," or "managed" instead of "manned"
  • Use "blocklist/allowlist" instead of "blacklist/whitelist"
  • Use "primary/replica" instead of "master/slave"
  • Use gender-neutral pronouns like "they/them" when the gender is unknown

Internet slang

Avoid using internet slang or abbreviations that may not be universally understood. For example, use "you" instead of "u", "please" instead of "plz", and "thank you" instead of "thx".
This ensures clarity and professionalism in documentation.

Latin

Avoid using Latin phrases or abbreviations like "i.e.", "e.g.", "etc.", "et al.", or "cf." in documentation.
Instead, use plain English equivalents to ensure clarity for all readers.
For example: use "for example" instead of "e.g." and "that is" instead of "i.e.".

Spatial references

Avoid using spatial references like "above", "below", "left", or "right" to describe content placement.
Instead, use more descriptive terms that indicate the content's function or purpose.
For example: "The settings menu allows users to configure preferences" instead of "See the settings menu above for configuration options."

Spelling

Use American English spelling for consistency.
For example: "color" instead of "colour", "organize" instead of "organise", "realize" instead of "realise".
If you use a spell checker, set it to American English.

Word list

A predefined list of words and their suggested alternatives.

Formatting and punctuation

Acronyms and initialisms

Don't use periods with acronyms or initialisms, such as "H.T.M.L.".
Spell out unfamiliar acronyms on first use of every page or document, followed by the acronym in parentheses.
For example: "Integrated Development Environment (IDE)."

No need to spell out common acronyms, for example: "API", "FAQ", "HTML", "PDF", "URL".

AM/PM

Use "AM" or "PM" (preceded by a space) for time references.

Correct: "10 AM" or "2 PM"
Incorrect: "10AM", "10am", "10a.m.", or "10 a.m."

Ellipses

In general, don't use an ellipsis (...) unless indicating missing text in a quote.

Acceptable: "The documentation states: 'The API supports multiple formats... including JSON and XML.'"
Avoid: "Click the button... and wait for the response" or "Loading..."

Em dashes

Use em dashes to set off additional information or explanations within a sentence. Em dashes can replace commas or parentheses for emphasis or clarity.

Don't use a space before or after a dash.

Correct: "The project—a collaborative effort—was completed ahead of schedule."
Incorrect: "The project — a collaborative effort — was completed ahead of schedule."

The only visual difference is their width. The em dash "—" is wider than the hypen "‐".

Mac: Press Option + Shift + - to type an em dash.
Windows: Hold down the Alt key and type 0151 on the numeric keypad to type an em dash.
Android/iOS: Hold down the hyphen key on the virtual keyboard to access the em dash option.
Microsoft Word/Google Docs: Typ two hyphens in a row "--" followed by a space or text and it will automatically convert to an em dash.

Exclamation points

Don't use exclamation points in text.

Correct: "This feature is now available" or "Complete the setup process"
Incorrect: "This feature is now available!" or "Complete the setup process!"

Hyphened adverbs

Words ending in "-ly" don't need a hyphen when they modify another word:
Use "highly configurable system" instead of "highly-configurable system"

Correct: "easily accessible interface," "frequently used feature"
Incorrect: "easily-accessible interface," "frequently-used feature"

Number ranges

Don't add words such as 'from' or 'between' to describe a range of numbers.
Use a hyphen to indicate a range of numbers, such as "10-20" or "100-200".
Don't use "to" or "through" to indicate a range.

Correct: "10-20"
Incorrect: "10 to 20" or "10 through 20"

Oxford comma

Use the Oxford comma. The comma before "and" or "or" in a series of three or more items removes ambiguity.
Correct: "I like cats, dogs, and rabbits."
Incorrect: "I like cats, dogs and rabbits."

Ordinal numbers

Spell out ordinal numbers (first, second, third, etc.) in text instead of using numerals (1st, 2nd, 3rd, etc.).

Parentheses

Limit your use of parentheses. Consider whether the information would work better as a separate sentence or phrase.

Better: "The API supports JSON format. This format is widely used in web development."
Instead of: "The API supports JSON format (which is widely used in web development)."

Plurals

Don't use plurals in parentheses such as "file(s)".
Choose either the singular or plural form.

Correct: "Upload the file" or "Upload files"
Incorrect: "Upload the file(s)"

Quotation marks

Commas and periods go inside quotation marks.

Correct: "Upload the files."
Incorrect: "Upload the files".

Semicolons

Use semicolons judiciously. Consider whether a period or a conjunction would work better.

Correct: "The API returns JSON data. The format is well-documented."
Correct: "The API returns JSON data, and the format is well-documented."
Questionable: "The API returns JSON data; the format is well-documented."

Spacing

Use one space after periods, question marks, and exclamation points. Don't use two spaces.

Correct: "First sentence. Second sentence."
Incorrect: "First sentence.  Second sentence." (two spaces)

Units of measure

Put a nonbreaking space between the number and the unit:

  • For data measurements: B, kB, MB, GB, TB
  • For time measurements: ns, ms, s, min, h

Correct: "The file is 5 MB" or "The process takes 30 ms"
Incorrect: "The file is 5MB" or "The process takes 30ms"