Add reference documentation use cases guide

docs.json

@@ -282,6 +282,7 @@
                   "guides/accessibility",
                   "guides/content-types",
                   "guides/content-templates",
+                  "guides/reference-use-cases",
                   "guides/improving-docs",
                   "guides/internationalization",
                   "guides/linking",

guides/reference-use-cases.mdx

@@ -0,0 +1,90 @@
+---
+title: "Reference documentation use cases"
+description: "Understand when and how to use reference documentation effectively."
+---
+
+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](/guides/content-types) 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.
+
+```json
+{
+  "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.
+
+## Related pages
+
+<CardGroup cols={2}>
+  <Card title="Content types" icon="shapes" href="/guides/content-types">
+    Choose the right content type for your documentation goals.
+  </Card>
+  <Card title="Content templates" icon="file-text" href="/guides/content-templates">
+    Copy and modify templates for different content types.
+  </Card>
+  <Card title="API documentation" icon="file-json" href="/api-playground/overview">
+    Learn how to document APIs with OpenAPI specifications.
+  </Card>
+  <Card title="Style and tone" icon="pen" href="/guides/style-and-tone">
+    Write effective documentation with consistent style.
+  </Card>
+</CardGroup>