Skip to main content
Use reference documentation when users need to look up specific details about your product’s functionality. Reference docs serve as the authoritative source for technical specifications, parameters, and options.

​
When to use reference documentation

Reference documentation works best for:
  • API endpoints: Document request parameters, response fields, authentication methods, and error codes.
  • Configuration options: List all available settings, their data types, default values, and valid ranges.
  • Component properties: Specify props, attributes, and customization options for UI components or libraries.
  • Command-line tools: Detail commands, flags, arguments, and their behaviors.
  • Data schemas: Define database tables, object structures, and field specifications.

​
Key characteristics

Reference documentation prioritizes:
  • Accuracy: Every detail must be correct and up-to-date.
  • Consistency: Use uniform formatting, terminology, and structure across all reference pages.
  • Scannability: Users should quickly find specific information without reading everything.
  • Completeness: Document all options, even rarely-used ones.

​
What reference docs are not

Reference documentation is not the place for:
  • Step-by-step tutorials: Use how-to guides instead.
  • Conceptual explanations: Create explanation pages for understanding complex topics.
  • Getting started content: Write tutorials or quickstarts for new users.
  • Marketing content: Keep reference docs technical and factual.

​
Common use cases

​
API documentation

Document REST APIs, GraphQL schemas, or RPC methods with complete parameter and response specifications. 
{
  "endpoint": "/api/users",
  "method": "POST",
  "parameters": {
    "name": "string (required)",
    "email": "string (required)",
    "role": "string (optional, default: 'user')"
  }
}

​
SDK and library references

Provide complete documentation for classes, methods, functions, and their signatures.

​
Configuration files

List all available configuration options for tools, frameworks, or applications.

​
CLI commands

Document command syntax, flags, and usage patterns for command-line interfaces.

​
Best practices

  • Start with a one-sentence description of what the feature or API does.
  • Use consistent formatting for all parameters and properties.
  • Include code examples showing typical usage.
  • Specify data types, default values, and whether fields are required.
  • Link to related reference pages and how-to guides.
  • Keep descriptions brief and end them with periods.

Content types

Choose the right content type for your documentation goals.

Content templates

Copy and modify templates for different content types.

API documentation

Learn how to document APIs with OpenAPI specifications.

Style and tone

Write effective documentation with consistent style.