Skip to content

existential-birds/beagle / plugins/beagle-docs/skills/docs-style

docs-style

Unverified

Core technical documentation writing principles for voice, tone, structure, and LLM-friendly patterns. Use when writing or reviewing any documentation.

Documentation Style Guide

Apply these principles when writing or reviewing documentation to ensure clarity, consistency, and accessibility for both human readers and LLMs.

Choose the Right Documentation Type First

Style serves a purpose, and the purpose depends on which of the four Diataxis types you are writing. Before applying the conventions below, decide whether the document is a Tutorial (learning), How-To guide (a task), Reference (looking up), or Explanation (understanding) — these are not interchangeable, and mixing them in one document weakens all of them.

To choose, ask the two compass questions: action or cognition? acquisition or application?

The reader's stanceType
"I'm learning — guide my hands"Tutorial
"I have a goal — help me reach it"How-To
"I'm working — let me look something up"Reference
"I'm reflecting — help me understand why"Explanation

For the full decision procedure, the 2×2 map, the two distinctions that resolve most ambiguity (Tutorial vs. How-To, Reference vs. Explanation), and the quality model, see references/diataxis-compass.md. The type-specific skills (tutorial-docs, howto-docs, reference-docs, explanation-docs) build on the principles in this guide once the type is chosen.

Voice and Tone

Use Second Person

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.

Prefer Active Voice

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.

Be Concise

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 ofUse
in order toto
for the purpose ofto, for
in the event thatif
at this point in timenow
due to the fact thatbecause
it is necessary toyou must
is able tocan
make use ofuse

Document Structure

Write Clear, Descriptive Headings

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)

Create Self-Contained Pages

Assume readers may land on any page directly from search. Each page should:

  • Explain what the feature/concept is
  • State prerequisites clearly
  • Provide complete context for the topic
<!-- 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

...

Use Semantic Markup

Choose the right format for the content type:

  • Headings: Follow proper hierarchy (h1 > h2 > h3, never skip levels)
  • Lists: Use for multiple related items
  • Tables: Use for structured data with consistent attributes
  • Code blocks: Use for any code, commands, or file paths
<!-- 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

Make Content Skimmable

Break dense paragraphs into digestible chunks:

  • Keep paragraphs to 3-4 sentences maximum
  • Use bullet points for lists of items
  • Add subheadings to long sections
  • Put key information first (inverted pyramid)
<!-- 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.

Consistency

Use One Term Per Concept

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:

ConceptUseDon't use
Authentication credentialAPI keyAPI token, secret key, access key
Configuration fileconfig filesettings file, preferences file
Command lineCLIterminal, command prompt, shell

Apply Consistent Formatting

Use the same formatting for similar content types:

  • UI elements: Bold (Click Save)
  • Code/commands: Backticks (npm install)
  • File paths: Backticks (/etc/config.yaml)
  • Key terms on first use: Bold or italics
  • Placeholders: SCREAMING_CASE or angle brackets (YOUR_API_KEY or <api-key>)

LLM-Friendly Patterns

State Prerequisites Explicitly

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**)

Define Acronyms on First Use

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.

Provide Complete, Runnable Code Examples

Code examples should work when copied. Include:

  • All necessary imports
  • Realistic placeholder values
  • Expected output (when helpful)
<!-- 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
---
title: "Authentication - API Reference"
description: "Learn how to authenticate API requests using API keys, OAuth 2.0, or service accounts."
---

Pitfalls to Avoid

Don't Use Product-Centric Language

Orient documentation around user goals, not product features.

<!-- Good: User-goal oriented -->
# Send Emails

Send transactional emails to your users with delivery tracking.

<!-- Avoid: Product-centric -->
# Email Service

Our powerful email service provides enterprise-grade delivery.

Skip Obvious Instructions

Don't document self-explanatory UI actions.

<!-- Good: Meaningful instruction -->
Enter your webhook URL. The URL must use HTTPS and be publicly accessible.

<!-- Avoid: Obvious instruction -->
Click in the text field. Type your webhook URL. Click the Save button.

Avoid Colloquialisms

Colloquialisms hurt clarity and localization.

<!-- Good -->
This approach significantly improves performance.

<!-- Avoid -->
This approach is a game-changer for performance.
This will blow your mind.
Let's dive in!

Two Kinds of Quality

Good documentation has two layers of quality, and the second depends on the first:

  • Functional quality — objective and measurable: accuracy, completeness, consistency, usefulness, precision. This is the prerequisite. The principles in this guide and the type-specific skills target functional quality.
  • Deep quality — subjective and human-centred: it feels good to use, anticipates the reader, and fits how people actually work. You cannot reach it without functional quality first; choosing the right type (above) and writing it cleanly lays the conditions for it.

See references/diataxis-compass.md for the full quality model and the "work by improvement" approach (improve one real piece at a time; never build empty section skeletons).

Quick Reference Checklist

When writing documentation, verify:

  • The document is one clear Diataxis type, not a mix (see the compass)
  • Using "you" instead of "the user"
  • Active voice throughout
  • No unnecessary words
  • Headings are descriptive
  • Page is self-contained
  • Proper heading hierarchy
  • One term per concept
  • Prerequisites listed
  • Acronyms defined
  • Code examples are complete
  • No product-centric language
  • No colloquialisms

Applying This Skill

Use these principles when:

  1. Writing new documentation: Apply all principles from the start
  2. Reviewing documentation: Check against the quick reference checklist
  3. Editing existing docs: Prioritize voice/tone, then structure, then consistency
  4. Creating code examples: Ensure they are complete and runnable
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 463kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall