cap-001 must GuidesAPI docsMarketingBlog Use sentence case for all headings, page titles, navigation items, button labels, and UI text: capitalize only the first word and proper nouns; lowercase everything else.
Capitalization
This guide uses sentence case everywhere — headings, UI text, tables, and captions. These rules define what that means in practice and how to handle proper nouns, brand styling, and text after colons.
Use sentence case
Section titled “Use sentence case”Examples
- ✓ ## Set up your development environment
- ✗ ## Set Up Your Development Environment
Rationale
Sentence case is easier to apply consistently than title case, whose rules vary between guides and create visible inconsistency across authors. It also lets proper nouns and code identifiers stand out, and it matches current developer-documentation practice.
Sentence case in captions and tables
Section titled “Sentence case in captions and tables”cap-007 should GuidesAPI docsMarketingBlog Use sentence case for captions, figure labels, callouts, list items, glossary terms, glossary definitions, and all table elements (contents, headings, labels, captions).
Examples
- ✓ Table 1. Supported response formats
- ✗ Table 1. Supported Response Formats
Rationale
Applying sentence case to captions, labels, and table text keeps casing consistent across the page.
Hyphenated words at the start
Section titled “Hyphenated words at the start”cap-008 should GuidesAPI docsMarketingBlog When a hyphenated word begins a sentence or heading in sentence-style capitalization, capitalize only the first element unless a later element is a proper noun or proper adjective.
Examples
- ✓ Built-in functions run faster than plugins.
- ✗ Built-In functions run faster than plugins.
Rationale
Only the first element is capitalized because the compound is one word; a later proper noun keeps its own capital.
Referenced titles and headings
Section titled “Referenced titles and headings”cap-011 should GuidesAPI docsMarketingBlog When referencing a title or heading from a document that follows this guide, use sentence case even if the original uses title case.
Examples
- ✓ See “Getting started with the CLI” in the reference guide.
- ✗ See “Getting Started With The CLI” in the reference guide.
Rationale
Applying this guide’s sentence case to a referenced heading keeps citations consistent with the rest of the content.
Capitalize proper nouns
Section titled “Capitalize proper nouns”cap-002 should GuidesAPI docsMarketingBlog Always capitalize proper nouns, including brand, product, and service names, regardless of surrounding capitalization style.
Examples
- ✓ ## Migrate your data to Example Cloud
- ✗ ## Migrate your data to example cloud
Rationale
Proper nouns are capitalized regardless of surrounding style so brand and product names stay correct.
Lowercase brand names at sentence start
Section titled “Lowercase brand names at sentence start”cap-010 should GuidesAPI docsMarketingBlog When possible, rewrite sentences and headings so they don’t begin with a product or brand name that’s stylized in lowercase (iPad, macOS, npm). Preserve the canonical capitalization rather than capitalizing the first letter. If rewriting would produce awkward phrasing, retain the lowercase form at the start.
Examples
- ✓ The npm client installs the dependencies listed in your manifest.
- ✗ Npm installs the dependencies listed in your manifest.
Rationale
A lowercase-styled product name like “iPad” or “macOS” carries its capitalization as part of the brand. Rewriting so a sentence doesn’t start with it preserves both the brand and normal sentence capitalization; keeping the lowercase form is better than capitalizing it when a rewrite would read worse.
No internal capitalization
Section titled “No internal capitalization”cap-004 should GuidesAPI docsMarketingBlog Do not use internal capitalization (AutoScale, e-Book) unless it is part of an official brand or product name.
Examples
- ✓ The service supports autoscaling and an ebook export format.
- ✗ The service supports AutoScaling and an e-Book export format.
Rationale
Mid-word capitals read as brand styling, so using them for ordinary words is confusing.
Lowercase after a colon
Section titled “Lowercase after a colon”cap-005 should GuidesAPI docsMarketingBlog In body text (outside titles and headings), use a lowercase letter after a colon unless the following text is a proper noun, a quotation, or follows a special label such as Note or Caution.
Examples
- ✓ The command has two modes: interactive and batch.
- ✗ The command has two modes: Interactive and batch.
Rationale
Within a sentence the text after a colon continues the thought, so it stays lowercase unless it is a name, quotation, or label.
No all caps for emphasis
Section titled “No all caps for emphasis”cap-003 should GuidesAPI docsMarketingBlog Do not use all-uppercase text for emphasis or as a design choice in body text.
Examples
- ✓ Never commit your API key to the repository.
- ✗ NEVER commit your API key to the repository.
Rationale
All caps is harder to read and can be spelled out letter by letter by screen readers, so use real emphasis instead.
No all lowercase as a style
Section titled “No all lowercase as a style”cap-012 should GuidesAPI docsMarketingBlog Do not use all-lowercase as a design choice.
Examples
- ✓ ## Getting started
- ✗ ## getting started
Rationale
All lowercase as a style choice hurts readability and, for proper nouns, is simply wrong.
Describe casing, and name it only alongside a description
Section titled “Describe casing, and name it only alongside a description”cap-006 should GuidesAPI docsMarketingBlog When you state a casing requirement, describe it explicitly and give an example; you may also name the casing style (such as ‘camel case’, ‘snake case’, or ‘kebab case’), but don’t rely on the name alone.
Examples
- ✓ Write the field name in camel case — a lowercase first word with each later word capitalized, as in
maxRetryCount. - ✗ Write the field name in camel case.
Rationale
A reader may not know what “camel case”, “snake case”, or “dash case” means, so the description and example carry the requirement; the style name is a helpful label when paired with them but is ambiguous on its own.
Don’t distinguish terms by case alone
Section titled “Don’t distinguish terms by case alone”cap-009 should GuidesAPI docsMarketingBlog Do not rely on a difference in capitalization alone to convey a semantic distinction between terms.
Examples
- ✓ Use “the hosted registry” for the managed service and “a self-hosted registry” for your own instance.
- ✗ Use “Registry” for the managed service and “registry” for your own instance.
Rationale
A reader cannot reliably tell two terms apart by capitalization alone, so meaning should not hinge on it.