Documentation Writer

Documentation Writer

Use this skill for all docs edits in src/routes/(docs)/docs/content/ and when updating docs navigation in src/routes/(docs)/docs.json.

Non-negotiable rules

1. Be concise: remove repetition and background that does not help the user complete a task.
2. Be actionable: prioritize “what to do” over theory.
3. One source of truth: if another page already has details, link to it instead of duplicating.
4. Preserve structure: keep valid frontmatter and heading anchor IDs.
5. Keep examples copyable: minimal, tested-looking, and directly relevant.
6. Search before writing: always check if the content already exists in some form before adding new sections or pages.
7. Check Relevant Code: Search the codebase inside src/ for any relevant code, comments, or tests that can inform the documentation content and ensure accuracy.

Docs config model (current)

docs.json is versioned. Sidebar lives inside tabs:

• versions[].content.navigation.tabs[].sidebar
• Sidebar groups contain pages
• Page paths use content (legacy slug may still appear in older content)

When adding a new doc page, add it to the appropriate tab sidebar path.

Versioned link policy (mandatory)

• For v4 docs content, internal links MUST use explicit v4 paths: /docs/v4/....
• Do not use unversioned shortcuts like /docs/alerting/... in v4 pages.
• Before finalizing, verify every internal link in edited files resolves to the intended version.

Required page format

---
title: Page Title
description: One-line summary of user outcome
---

• Use custom anchors for H2/H3 headings: ## Section {#section}
• Use GitHub admonitions only when needed: [!NOTE], [!IMPORTANT], [!WARNING], [!CAUTION], [!TIP]
• Prefer short sections and short lists

Preferred structure (default)

1. Short intro (1–2 sentences)
2. Quick setup / minimum config
3. Required variables/options table
4. Verification step
5. Top troubleshooting items

Only add extra sections if they materially improve task completion.

Keep docs lean

Remove or avoid:

• Multiple near-identical examples
• Long conceptual explainers
• Platform-by-platform repetition unless behavior differs
• Large checklists that restate earlier content

Editing workflow

1. Read the whole target document.
2. Compress verbose sections first.
3. Keep critical caveats and breaking notes.
4. Ensure internal links and anchors still work.
5. If adding files, update docs.json navigation in the correct version/tab.

Review checklist

• Title/description frontmatter exists
• Key steps are clear and copyable
• Content is concise and non-duplicative
• Headings keep stable custom anchors
• Navigation updated (if new page)
• Internal links point to correct paths
• v4 pages use /docs/v4/... internal links (no unversioned /docs/... shortcuts)
• No outdated or irrelevant content remains
• Admonitions used appropriately for important notes