Reference articles

What Is a Reference Article?

A reference article is a structured, exhaustive catalogue of a specific set of information. It answers the question "What are all the options/values/settings for X?" Readers do not read reference articles from top to bottom — they scan or search for specific entries. The primary design principle for reference content is scanability and completeness. See the Reference Articles section of the Five Core Content Types guide for how this type relates to the other four; this article is the fuller treatment of that entry.

When to write a reference article: when readers need to look up specific values, parameters, settings, API fields, keyboard shortcuts, or configuration options. Reference articles accompany how-to and conceptual articles but do not replace them.

Common reference article types include: API endpoints, configuration settings, keyboard shortcuts, field descriptions, error codes, and product glossaries.

Structure

Title

Use a noun phrase that names the thing being documented. Be specific.

• Article settings reference
• API tokens
• Keyboard shortcuts
• Supported file types

Opening (1–2 sentences)

State what the reference covers and any key context. Keep it minimal — readers came to look something up, not to read an introduction.

The reference content

Use tables as the default format for reference content, per the When to Use a Table guidance in the Lists and Tables guide. Tables let readers scan across rows and columns more efficiently than lists or prose.

Structure tables with consistent, descriptive column headers. Common column patterns:

For long reference tables (more than 20 rows), consider adding a brief navigation section or anchor links to help readers jump to the relevant part — see the Wide and Long Tables section of the Lists and Tables guide for the fuller treatment of this problem.

Notes and constraints

For settings or parameters with important constraints, add a callout directly beneath the relevant table row or section, using the standard Note/Tip/Important/Warning system defined in the Callouts guide. Do not bury constraints in the introductory prose.

Template

[Title — noun phrase, specific]

[1–2 sentence intro: what this reference covers and any key context]

## [Section heading if the reference has multiple distinct groups]

| [Column 1] | [Column 2] | [Column 3] | [Column 4] |
|---|---|---|---|
| [Value] | [Description] | [Default] | [Constraints] |
| [Value] | [Description] | [Default] | [Constraints] |

> **Note:** [Any constraint or important caveat that applies to the above]

## [Next section if needed]

Writing Reference Content

Reference content should be precise, consistent, and complete. Follow these guidelines:

• Every entry should be defined. Do not leave a table cell blank unless the field genuinely does not apply — and if so, use "—" or "N/A" rather than an empty cell.
• Use consistent terminology. Use exactly the same names that appear in the UI, API, or system being documented. Do not paraphrase.
• Document defaults explicitly. Readers frequently need to know what happens if they do not change a setting.
• State the data type for technical references. For API or configuration references, always include the data type: string, integer, boolean, enum.
• List all valid values for enums. If a field accepts a fixed set of values, list every one.
• Keep descriptions concise. One or two sentences per entry. If a setting requires detailed explanation, link to a conceptual or how-to article.
• Format numbers, dates, currency, and units consistently. Reference tables often contain default values and ranges that are exactly the kind of content most prone to locale ambiguity — see the Dates, Numbers, and Units for Localization guide for the formats to use.

Keeping Reference Content Accurate

Reference articles become inaccurate faster than any other content type because they document specific values that change with each product update. This is the reference-specific application of the review-cadence-by-content-type guidance in the Documentation Lifecycle guide, which already establishes that reference content should be tied to release cycles rather than a fixed calendar interval. Build a review process:

• Tag reference articles for review whenever the underlying feature ships a change.
• Use your knowledge base platform's review reminder tools, if available, to schedule periodic reviews as a backstop.
• Where possible, note the version or date the reference was last verified.

Tone

Neutral and precise. Reference articles have almost no prose — they are structured data. Descriptions should be factual and consistent. Avoid evaluative language ("This is the recommended setting") unless it is genuinely a documented recommendation — link to the guidance article instead.

Self-Audit Checklist

Before publishing, check the reference article against these questions:

• Does the title use a specific noun phrase naming exactly what's being documented?
• Is the intro minimal, without an unnecessary explanation before the reference content itself?
• Is the content structured as a table, using the column pattern appropriate to its content type?
• Are long tables (20+ rows) given navigation aids or anchor links?
• Are constraints and caveats placed as callouts next to the relevant row, not buried in prose?
• Are all table cells filled, with "—" or "N/A" used deliberately rather than left blank?
• Does terminology match the UI, API, or system exactly, with no paraphrasing?
• Are defaults stated explicitly for every setting or field?
• Are data types and full enum value lists included for technical references?
• Are numbers, dates, currency, and units formatted per the localization guidance?
• Is the article tagged for review tied to the next relevant feature release?
• Is the tone neutral and factual, with evaluative language only where it reflects a genuine documented recommendation?