These rules cover numerals versus spelled-out numbers, decimals and separators, ranges, units of measure, currency, phone numbers, and mathematical notation. Date and time formats have their own page, and hyphenation of number-unit modifiers like “a 30-second timeout” lives in punctuation.
num-001 should GuidesAPI docsMarketingBlog Spell out the numbers one through nine in body text; use numerals for 10 and above, and apply the same threshold to ordinals. Use numerals regardless of size for units of measure, reference contexts, code, tables, precise data values, version numbers, and identifiers. Don’t start a sentence with a numeral, spell out numbers in fixed idiomatic phrases, and avoid Roman numerals entirely.
Examples
Rationale
Single-digit numerals can be visually ambiguous in some typefaces (1 for l, 0 for O), while numerals of 10 and up are unmistakable. The threshold keeps the typography-safety benefit for small numbers and the scanning benefit for larger ones.
num-002 should GuidesAPI docsMarketingBlog Always use numerals for technical quantities (memory, disk space, query limits, version numbers, measurements, units of time) regardless of size.
Examples
Rationale
A technical quantity is read as data, so a numeral is scannable and unambiguous regardless of size.
num-003 should GuidesAPI docsMarketingBlog Do not begin a sentence with a numeral; rewrite the sentence or spell out the number.
Examples
Rationale
A numeral opening a sentence is easy to miss as the start, so recasting or spelling it out reads cleanly.
num-004 should GuidesAPI docsMarketingBlog When numbers in the same category appear in the same sentence or passage and any one requires a numeral, use numerals for all of them.
Examples
Rationale
Mixing spelled-out and numeral forms for like numbers in one passage looks inconsistent, so matching them reads evenly.
num-006 should GuidesAPI docsMarketingBlog For ordinal numbers larger than nine, use numerals with full-size (not superscript) st/nd/rd/th suffixes.
Examples
12<sup>th</sup> retry triggers a backoff alert.Rationale
Full-size suffixes are readable and, unlike superscripts, do not render inconsistently across viewers.
num-007 should GuidesAPI docsMarketingBlog Use numerals for percentages; do not spell out the number.
Examples
Rationale
A percentage is a data value, so a numeral with the percent sign is scannable.
num-008 should GuidesAPI docsMarketingBlog Place a zero before the decimal point for decimal fractions less than one (0.5, not .5).
Examples
Rationale
A leading zero makes a decimal below one obvious and stops “.5” from being misread.
num-010 should GuidesAPI docsMarketingBlog Use a period as the decimal point (standard American style).
Examples
num-009 should GuidesAPI docsMarketingBlog Use commas as thousands separators in numbers with four or more digits; don’t use commas in numbers with three or fewer digits. Exceptions that follow their own conventions: years, identifiers and port numbers, code samples, addresses, page and reference numbers, phone numbers, and currency.
Examples
Rationale
A thousands separator helps a reader judge magnitude at a glance, and four digits is where that help starts to matter. The exceptions such as years, identifiers, and code are numeric strings read as labels, not counted quantities.
num-018 should GuidesAPI docsMarketingBlog Avoid abbreviating thousand, million, and billion as K, M, B in body text; spell out the word or use the full number.
Examples
Rationale
“K”, “M”, and “B” are ambiguous and do not translate, so the spelled-out word or full number is clear.
num-023 should GuidesAPI docsMarketingBlog In ranges of numbers that include units, repeat the unit for each number and use ‘to’ rather than a hyphen or en dash.
Examples
Rationale
Repeating the unit and using “to” keeps a range unambiguous, as in “5 GB to 10 GB.”
num-024 should GuidesAPI docsMarketingBlog Don’t shorten the second number in a range; write it out in full (2013-2019, not 2013-19).
Examples
Rationale
Writing both ends of a range in full avoids the ambiguity of a shortened second number.
num-011 should GuidesAPI docsMarketingBlog Don’t let a number and its unit of measure separate across line breaks. In Markdown source, write a regular space between the number and the unit; the build process converts it to a nonbreaking space in rendered output.
Examples
Rationale
Splitting a number from its unit across a line break makes the pair briefly hard to read, which is most visible in PDF and narrow columns. Handling the nonbreaking space at build time keeps the source clean.
num-012 should GuidesAPI docsMarketingBlog Do not place a space between a number and the currency symbol or percent sign.
Examples
Rationale
The percent or currency symbol binds to its number, so a space would split the pair.
num-022 should GuidesAPI docsMarketingBlog Do not mix unit symbols with unit names (avoid ‘m/second’), or prefix names with unit symbols (avoid ‘kiloHz’).
Examples
Rationale
Mixing a symbol and a spelled-out unit is inconsistent and can be misread.
num-013 should GuidesAPI docs When documenting precise byte quantities, use the unit that matches the technology’s measurement system: decimal units (KB, MB, GB, TB) for technologies that use powers of 10, and binary units (KiB, MiB, GiB, TiB) for technologies that use powers of 2. Strict adherence is required in low-level technical documentation; loose adherence is acceptable in casual user-facing contexts.
Examples
Rationale
Decimal and binary byte units differ by roughly 7%, so using the wrong one in low-level documentation states a wrong figure. Matching the unit to the technology’s own measurement system keeps memory and buffer sizes accurate.
num-025 should GuidesAPI docsMarketingBlog Use the standard symbol for a unit of measure with its conventional casing, and write spelled-out unit names as one word (kilobyte, megahertz), not spaced or fused variants like “K byte” or “Kbyte”. Capitalize B for bytes and lowercase b for bits: MB is megabytes, Mb is megabits (not Mbit). Write data rates with a “ps” suffix, not a slash: MBps is megabytes per second and Mbps is megabits per second, not MB/s or Mb/s.
Examples
Rationale
Unit symbols have fixed, standard casing, and the bytes-versus-bits distinction (B versus b) changes a figure eightfold, so getting the symbol right keeps a quantity accurate. Writing spelled-out names as one word matches how readers expect to see them.
Common unit symbols
| Symbol | Spelled out |
|---|---|
| kHz, MHz, GHz | kilohertz, megahertz, gigahertz |
| KB, MB, GB, TB | kilobyte, megabyte, gigabyte, terabyte |
| Kb, Mb, Gb | kilobit, megabit, gigabit |
| KBps, MBps, GBps | kilobytes, megabytes, gigabytes per second |
| Kbps, Mbps, Gbps | kilobits, megabits, gigabits per second |
num-021 should GuidesAPI docsMarketingBlog For international documentation, express currency amounts with the ISO 4217 three-letter currency code (1199 USD) rather than currency symbols such as $.
Examples
Rationale
A three-letter currency code is unambiguous across regions, unlike a bare symbol that several countries share.
num-017 should GuidesAPI docsMarketingBlog Use ‘per’ instead of a slash for rates in body text (‘requests per day’); the slash is acceptable only in space-constrained contexts.
Examples
Rationale
“Per” is unambiguous for a rate, while a slash can read as a fraction or a division.
num-014 should GuidesAPI docsMarketingBlog Format North American phone numbers with hyphens separating area code, exchange, and number (415-555-0132); do not use parentheses around the area code.
Examples
Rationale
Hyphen-separated area code, exchange, and number is the readable North American form; parentheses add clutter.
num-015 should GuidesAPI docsMarketingBlog Format international phone numbers beginning with a plus sign and country code, with no space between the plus sign and the country code.
Examples
Rationale
A leading plus and country code make an international number diallable from anywhere.
num-016 should GuidesAPI docsMarketingBlog Use only example phone numbers from the reserved range (800-555-0100 through 800-555-0199) in documentation; never use real phone numbers in examples.
Examples
Rationale
The reserved range cannot ring a real person, so examples never expose a real number.
num-019 should GuidesAPI docsMarketingBlog Use HTML entities such as − and × rather than keyboard symbols for mathematical operators in HTML and Markdown documentation.
Examples
Rationale
HTML entities render the true minus and times signs, which the keyboard hyphen and letter x only approximate.
num-020 should GuidesAPI docsMarketingBlog Use the HTML <sup> tag for exponents; do not use the caret (^) symbol to indicate exponentiation in text.
Examples
2<sup>32</sup>.Rationale
A superscript shows an exponent correctly, while a caret is a keyboard stand-in that reads as literal text.
num-005 (retired 2026-07-17) — “Spell out all ordinal numbers in body
text.” Superseded: it contradicted the one-through-nine threshold that
num-001 applies to ordinals and the numeral-ordinal form num-006 requires
above nine. The ID stays reserved and is never reused.