Numbers, dates, and time

Inconsistent treatment of numbers, dates, and time creates small but persistent friction for readers — especially for a global audience where conventions vary significantly by region. This article establishes clear, unambiguous rules for every numeric context in documentation.

Numbers

When to spell out numbers

Spell out whole numbers from zero through nine. Use numerals for 10 and above.

Exceptions: always use numerals

Always use numerals — regardless of value — in the following contexts:

• Technical values and measurements: "a 4 GB file," "a 2-second delay"
• Version numbers: "version 3," "API v2"
• Steps in a procedure: "Step 3," "in step 7"
• Specific counts the reader needs to track: "select 2 of the 5 options"
• Numbers used as part of a proper name: "Web 2.0"
• Percentages: "a 3% increase," "a 25% increase" — always a numeral with the "%" symbol, regardless of value. Spell out "percent" only in the rare case where the numeral itself is being avoided entirely for stylistic reasons; in documentation, the numeral-plus-symbol form is the default and should be used consistently rather than switching based on the number's size.
• Ordinal numbers used technically or in sequences: "the 1st and 2nd fields," "3rd-party integration" is written as "third-party" in prose (see Hyphens, in the Punctuation guide) but ordinals referring to a numbered sequence in a UI or table ("1st," "2nd," "3rd") follow the same numerals-only convention as their cardinal counterparts.

Ordinal numbers in prose

Outside of technical or tabular contexts, treat ordinal numbers the same as cardinal numbers: spell out first through ninth, use numerals for 10th and above. "This is the third step in the setup process," not "the 3rd step." "This is the 12th article in the series."

Never start a sentence with a numeral

If a sentence must begin with a number, spell it out — or rewrite the sentence.

Correct: "Fifteen articles are included in the default template."
Better: "The default template includes 15 articles."

This rule takes precedence even over the "always use numerals" exceptions above. If a technical value would otherwise need to open a sentence — "3 GB is the maximum file size" — restructure the sentence instead of spelling out the value: "The maximum file size is 3 GB."

Large numbers

Use commas as thousands separators: 1,000 / 10,000 / 1,000,000. Do not use spaces or periods as thousands separators (both are used in other countries and will create ambiguity for a global audience).

Decimals

Use a period as the decimal separator: 3.5, 99.9%. Be aware that many countries use a comma as the decimal separator and a period for thousands — the reverse of the convention used here. Since documentation defaults to the comma-thousands, period-decimal convention, avoid constructing numbers where this reversal could cause genuine ambiguity (for example, clarify units or use words if a number like "1.234" could be misread as either "1,234" or "1.234").

Number ranges in prose

Use an en dash for ranges in tables, parenthetical, or clearly numeric contexts: "10–20 minutes," "pages 12–18." In running prose, "to" is often clearer and reads more naturally: "the process takes 10 to 20 minutes." Prefer "to" in sentences and the en dash in tables or condensed formats; do not mix both conventions for the same kind of range within one article.

Units of measurement

Include a space between a numeral and its unit: "4 GB," "10 ms," "2 hours." Do not close up the space ("4GB," "10ms") except when reproducing an exact value as it appears verbatim in the product interface.

Dates

Date format is one of the most frequent sources of confusion across regions. The date 03/04/2025 means April 3 in the United States, March 4 in the United Kingdom, and is ambiguous everywhere.

Use unambiguous date formats in all documentation:

Avoid all numeric-only date formats (03/04/25, 04-03-2025, 3/4/25) in documentation that will be read internationally.

When referring to a year range, use an en dash: 2023–2025.

Do not abbreviate month names in body text: write "November" not "Nov." Abbreviations are acceptable only in tables or tight-space UI contexts.

Time

Format

Use numerals for all times. Use a.m. and p.m. (lowercase, with periods) to indicate morning and afternoon. Include a space between the numeral and a.m./p.m.

Prefer the words "noon" and "midnight" alone over their numeral equivalents in both cases — not just for midnight. If a numeral is required for consistency with other times in a table or schedule, "12:00 p.m." and "12:00 a.m." are acceptable, but note that "12:00 a.m." is genuinely ambiguous to some readers and should include "(midnight)" in parentheses if used at all.

Time zones

Always include a time zone when documenting times that apply to specific events, deadlines, or maintenance windows. Use the time zone abbreviation: UTC, EST, PST. For documentation with a global audience, UTC is the safest reference point.

Example: "Maintenance is scheduled for 2:00 a.m. UTC on January 15."

Duration

Spell out units of duration: "15 minutes," "2 hours," "3 days." Do not abbreviate: not "15 min" or "2 hrs" unless in a table with a space constraint.

Percentages

Always use the percent symbol (%) with a numeral, regardless of the number's value: "a 3% increase," "a 25% increase." This is an explicit exception to the general zero-through-nine spelled-out rule — percentages are always written as a numeral plus the "%" symbol, never spelled out ("three percent") in standard documentation prose.

Currency

Use the currency symbol immediately before the numeral, with no space: 49, €99. For documentation read by an international audience, include the ISO currency code alongside the symbol on first use in an article to remove ambiguity between similarly symboled currencies: "49 USD," "1,000.00, not 1 000.

Phone Numbers

When including phone numbers, use the international format: +1 (555) 123-4567. This format works globally and clearly identifies the country code.

Self-Audit Checklist

Before publishing, check numbers, dates, and time against these questions:

• Are whole numbers zero through nine spelled out, and 10+ written as numerals, outside of the listed exceptions?
• Do all "always numerals" exceptions (measurements, versions, steps, specific counts, percentages) use numerals regardless of value?
• Does no sentence begin with a numeral, including exception cases — restructured instead where needed?
• Do large numbers use commas as thousands separators, never spaces or periods?
• Are decimals written with a period, with potentially ambiguous values clarified?
• Are number ranges consistent within their context — "to" in prose, en dash in tables?
• Is there a space between every numeral and its unit of measurement?
• Are all dates in an unambiguous format — written out in prose, ISO 8601 in technical contexts — never numeric-only?
• Are "noon" and "midnight" used as words rather than ambiguous 12:00 numerals wherever possible?
• Does every specific time include a time zone?
• Are percentages always written as a numeral with the "%" symbol?
• Do currency values include a currency code where the audience is international, and correct separator conventions?