Skip to content
Developer Experience Docs
The style guide is in beta: content and structure may change.

Dates and times

These rules cover how to write calendar dates, clock times, and seasonal references. For avoiding time-anchored wording like “currently” and “soon” in evergreen content, see the time-based content guidance; for general number formatting, see numbers and units.

Unambiguous date formats

Section titled “Unambiguous date formats”
datetime-001 should GuidesAPI docsMarketingBlog

Use unambiguous date formats: Month DD, YYYY in body text (January 19, 2017) and ISO 8601 (2017-01-19) in numeric contexts. Never use ambiguous numeric-only formats such as 1/19/17. Use four-digit years, and avoid seasons for global audiences; use months or quarters instead.

Examples

  • ✓ The certificate expires on January 19, 2027.
  • ✗ The certificate expires on 1/19/27.

Rationale

Numeric-only dates like 1/2/17 mean different things in different regions, so an unambiguous format prevents misreading. A written month in body text and ISO 8601 in numeric contexts are both unambiguous, and seasons are avoided because they invert across hemispheres.

ISO 8601 for numeric dates

Section titled “ISO 8601 for numeric dates”
datetime-002 should GuidesAPI docsMarketingBlog

When a numeric-only date format is required, use ISO 8601 (YYYY-MM-DD).

Examples

  • ✓ Set expiry to 2027-01-19.
  • ✗ Set expiry to 01-19-2027.

Rationale

ISO 8601 is unambiguous and sorts correctly, which suits numeric and machine contexts.

12-hour clock

Section titled “12-hour clock”
datetime-003 should GuidesAPI docsMarketingBlog

Use the 12-hour clock with AM/PM for times in general documentation.

Examples

  • ✓ The maintenance window opens at 9:00 PM.
  • ✗ The maintenance window opens at 21:00.

Rationale

The 12-hour clock with AM/PM matches how a general audience reads times.

Noon and midnight

Section titled “Noon and midnight”
datetime-004 should GuidesAPI docsMarketingBlog

Use ‘noon’ and ‘midnight’ instead of 12:00 PM / 12:00 AM.

Examples

  • ✓ The cleanup job runs daily at midnight.
  • ✗ The cleanup job runs daily at 12:00 AM.

Rationale

“12:00 PM” and “12:00 AM” are widely confused, so “noon” and “midnight” are unambiguous.

Avoid seasons

Section titled “Avoid seasons”
datetime-005 should GuidesAPI docsMarketingBlog

Do not refer to seasons; use months, quarters, or temperature instead. If a season must be mentioned, specify the hemisphere.

Examples

  • ✓ Support for the legacy endpoint ends in the third quarter of 2027.
  • ✗ Support for the legacy endpoint ends in summer 2027.

Rationale

Seasons are opposite across hemispheres, so a month or quarter is unambiguous for a global audience.