Style for Different Content Types (A–Z)
in Style Guide
Abbreviations
Expanding abbreviations
Spell out an abbreviation the first time you use it on a page. Put the short form in parentheses afterwards. After that, you can just use the abbreviation.
There are a few ways you can do this — see techniques for expanding abbreviations.
Exception: If a term is widely known by its abbreviation, you do not need to spell it out.
Re-expanding abbreviations
- Independent sections: In sections that may be read independently of the main text, spell out the abbreviation again, followed by the abbreviation in parentheses.
- Change of context: If an abbreviation could have multiple meanings and the context changes, provide the full meaning to clarify which meaning is intended.
Capitalization in abbreviations
Use title case for proper nouns.
Use lowercase for common nouns.
Abbreviations to avoid
- e.g.: Use “for example”.
- etc.: Start the phrase with “such as” to indicate other possible options.
- i.e.: Use “that is” or “in other words”.
- vs.: Use “versus”, “compared with”, or “in contrast to”.
Dates
Put the day first:
Do not use letter suffixes after the day:
Use numbers for the day and year, words for the month:
If numbers only are required, use YYYY-MM-DD:
Headings
Correct heading hierarchy
Nest headings properly — for example, <h1> should not be followed by <h3> or lower.
See also the guidance on structuring headings.
Capitalization in headings
Use sentence case, not title case.
Exception: Capitalize any terms in the heading that are proper nouns.
Punctuation in headings
Use no terminal punctuation for headings, unless a question mark is required.
Links
Link text
Link text should describe the destination.
On a given page, do not use the same link text for links that go to different destinations.
In-line links
Place links at the end of sentences, if possible.
Links to non-HTML documents
Include the file format so the user knows what to expect.
Punctuation in links
Add a full stop after the linked text if it ends a sentence.
Do not add a full stop a raw URL.
Lists
Parallel structure
Keep the same grammatical form for each list item: all noun phrases, all verb phrases, or all full sentences.
Long list items
When items in a list have several sentences, consider if the list structure is particulary useful for conveying the information. If not, use regular paragraphs instead of a list.
Capitalization and punctuation in lists
Text that introduces a list
End with a colon.
List items are complete sentences
Capitalize the first letter.
End with a full stop or a question mark.
List items are fragments or not complete sentences
Start with a lowercase letter (except for proper nouns).
End each item with no punctuation.
List items complete the introductory phrase or sentence in the body text
Treat all the items in the list as a grammatical part of the introductory phrase or sentence.
Start with a lowercase letter, even if the list is a numbered list.
End each item with no punctuation.
List items that are a mix of complete sentences and fragments
If you must mix sentences and fragments, start with a capital letter and end with a full stop or question mark for all items.
Numbers
When to write as digits
Ages, measurements, percentages, and ratios
Always use a digit:
Digits versus words
Numbers showing quantity or order
Numbers up to nine: use words.
Numbers 10 and above: use digits.
Exceptions:
- See Ages, measurements, percentages, and ratios.
- Use words for very large, rounded numbers.
Start of a sentence
Avoid starting a sentence with a digit. Use words or reword.
Related numbers
With related numbers, where one number is usually written in digits and the other not, use digits for both.
Adjacent numbers
With adjacent numbers that express different categories of numbers, use a mixture of words and digits.
Punctuation in numbers
Use commas in numbers with more than three digits.
Exceptions: Use no punctuation for years, addresses, page numbers, or code line numbers.
Symbols
Except where there is a lack of space (for example, in a table or chart), use words for the following symbols:
- Ampersand:
- &: Use “and” instead.
- Number sign (octothorpe):
- #: Use “number” or a suitable noun instead.
Times
- Use the 24-hour clock.
- In a sentence, do not use the en dash. Use “from … to” or “between … and” instead.