Core technical documentation writing principles for voice, tone, structure, and LLM-friendly patterns. Use when writing or reviewing any documentation.
Apply these principles when writing or reviewing documentation to ensure clarity, consistency, and accessibility for both human readers and LLMs.
Address the reader directly as "you" rather than "the user" or "developers."
<!-- Good -->
You can configure the API by setting environment variables.
<!-- Avoid -->
The user can configure the API by setting environment variables.
Developers should configure the API by setting environment variables.
Write sentences where the subject performs the action. Active voice is clearer and more direct.
<!-- Good -->
Create a configuration file in the root directory.
The function returns an array of user objects.
<!-- Avoid -->
A configuration file should be created in the root directory.
An array of user objects is returned by the function.
Cut unnecessary words. Every word should earn its place.
<!-- Good -->
Run the install command.
<!-- Avoid -->
In order to proceed, you will need to run the install command.
<!-- Good -->
This endpoint returns user data.
<!-- Avoid -->
This endpoint is used for the purpose of returning user data.
Common phrases to simplify:
| Instead of | Use |
|---|---|
| in order to | to |
| for the purpose of | to, for |
| in the event that | if |
| at this point in time | now |
| due to the fact that | because |
| it is necessary to | you must |
| is able to | can |
| make use of | use |
Headings should tell readers exactly what the section contains. Avoid clever or vague titles.
<!-- Good -->
## Install the CLI
## Configure Authentication
## Handle Rate Limits
<!-- Avoid -->
## Getting Started (vague)
## The Fun Part (clever)
## Misc (uninformative)
Assume readers may land on any page directly from search. Each page should:
<!-- Good: Self-contained -->
# Webhooks
Webhooks let you receive real-time notifications when events occur in your account.
## Prerequisites
- An active API key with webhook permissions
- A publicly accessible HTTPS endpoint
## Create a Webhook
...
Choose the right format for the content type:
<!-- Good: Table for structured data -->
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| api_key | string | Yes | Your API key |
| timeout | integer | No | Request timeout in seconds |
<!-- Good: List for steps or options -->
To authenticate, you can:
- Use an API key in the header
- Use OAuth 2.0
- Use a service account
Break dense paragraphs into digestible chunks:
<!-- Good: Skimmable -->
## Error Handling
The API returns standard HTTP status codes.
### Common Errors
- **400 Bad Request**: Invalid parameters. Check the request body.
- **401 Unauthorized**: Invalid or missing API key.
- **429 Too Many Requests**: Rate limit exceeded. Wait and retry.
### Retry Strategy
For 429 errors, use exponential backoff starting at 1 second.
Pick a term and use it consistently. Switching terms confuses readers.
<!-- Good: Consistent terminology -->
Generate an API key in the dashboard. Use your API key in the Authorization header.
<!-- Avoid: Inconsistent terminology -->
Generate an API key in the dashboard. Use your API token in the Authorization header.
Document your terminology choices:
| Concept | Use | Don't use |
|---|---|---|
| Authentication credential | API key | API token, secret key, access key |
| Configuration file | config file | settings file, preferences file |
| Command line | CLI | terminal, command prompt, shell |
Use the same formatting for similar content types:
npm install)/etc/config.yaml)YOUR_API_KEY or <api-key>)List what users need before starting. This helps both humans and LLMs understand context.
## Prerequisites
Before you begin, ensure you have:
- Node.js 18 or later installed
- An active account with admin permissions
- Your API key (find it in **Settings > API**)
Spell out acronyms the first time they appear on a page.
<!-- Good -->
The CLI (Command Line Interface) provides tools for managing your resources.
Subsequent uses can just say "CLI."
<!-- Avoid -->
The CLI provides tools for managing your resources.
Code examples should work when copied. Include:
<!-- Good: Complete example -->
```python
import requests
API_KEY = "your-api-key"
BASE_URL = "https://api.example.com/v1"
response = requests.get(
f"{BASE_URL}/users",
headers={"Authorization": f"Bearer {API_KEY}"}
)
print(response.json())
# Output: {"users": [{"id": 1, "name": "Alice"}, ...]}
response = requests.get(url, headers=headers)
### Write Descriptive Titles and Meta Descriptions
Page titles and descriptions help with search and LLM understanding.
```markdown
---