kent.sh docs-writing skill

SKILL.md

name	docs-writing
description	How to write public product documentation. Use when editing README.md, AGENTS.md, ./docs/ contents, any documentation website content, user guides and similar documentation pages.

Goal

Public docs should be stable, terse, standalone, and user-facing. Document the product as it is, not the story of how it got there.

Core rules

1. Write timelessly

• Ban temporal or transition language unless it is part of a literal product contract.
• Avoid: currently, now, no longer, still, yet, for now, initial, first rollout, later, recently, WIP etc.
• Prefer present-state statements: what exists, what users can do, what happens on failure.

2. No changelog voice

• Do not mention work done, rollout stage, validation exercises, migration status, your mistakes, or why the team implemented something.
• Bad: "the first built-in processor is intentionally tiny".
• Good: describe the actual behavior and limits.

3. Keep each page self-contained

• A page must explain its own subject only without duplicating content across pages.
• Cross-link only for adjacent topics or exhaustive reference after the local explanation is already sufficient.

4. One fact, one place

• Pick an owning page for each concept.
• Do not repeat the same explanation, defaults, caveats, or flag semantics across multiple pages.
• If another page must mention the concept, keep it to one short contextual sentence.
• Aggressively eliminate duplicates when adding or consolidating content.

5. Compress aggressively

• Prefer one precise sentence over setup, rationale, and restatement.
• Remove throat-clearing like This is meant to, In other words, supported interface, feature <product> uses internally.
• Keep examples few and representative. Do not stack near-duplicate examples.

6. Do not document internals that aren't relevant to the end user

• Include mechanics only when they change usage, configuration, output, failure mode, or compatibility.
• Omit architecture-validation notes, internal rollout notes, and implementation details that do not change user action. Bad: "kent creates a database table to track worktrees"; "kent resolves local directories and symlinks first, then root folder files"; "this command will validate your input"; "server connection is automatic".

7. Avoid roadmap, editorial, and legal speculation

• Do not document guesses, opinions, or future-facing caveats such as will be supported, likely never.
• Public docs should describe shipped behavior and stable constraints.

8. Assume an expert reader

• Do not explain generic UI conventions, obvious command shapes, or labels the user can already see.
• Avoid describing page layout, button placement, row contents, badges, or standard keys like Enter, arrows, Esc, q, PgUp, PgDn.
• Do not add action columns or prose for self-explanatory commands.
• Document only non-obvious semantics: matching rules, side effects, defaults, blockers, failure behavior, and configuration.
• Owner pages must not have page-tour, layout, or keybinding sections unless the UI itself is unusual enough that the interaction is not discoverable.
• Do not document autofill logic, suggestion logic, field enable/disable rules, or defaulting algorithms unless they create a non-obvious operator-visible constraint.

8. Do not refer to the user's local setup, working environment assumptions, do not leak names or PII.

• Assume docs are read/used by people on different systems, machines, and are public on the internet.
• Do not leave user names ("Nikita", "Pete"), emails, mentions of "User" or "assistant", OS configurations, local scripts, skills, local docs that you haven't verified are committed and already public, outside repo or folder references, anywhere in the docs.

Bad vs good

Temporal wording

• Bad: Kent no longer rewrites command output.
• Good: Kent preserves command execution and can post-process displayed output.
• Bad: For now, only OpenAI is supported.
• Good: Kent supports OpenAI authentication via OAuth or API key.

Changelog voice

• Bad: The first rollout is intentionally tiny to validate the architecture.
• Good: Successful direct simple \go test ...` commands collapse to `PASS`.`

Repeated explanations

• Bad: repeating semantics of configuration in quickstart, settings, troubleshooting, and feature docs.
• Good: let settings.md own configuration e2e and mention it from other pages with in-context links.

Obvious UI

• Bad: a table row | /wt | Open the Worktrees page |.
• Good: list only the command forms when the syntax already explains the action.
• Bad: explaining that Enter confirms or that a page shows badges already visible on screen.
• Good: explain how worktree target matching works, what delete blocks on, and where managed worktrees are created.

Local references & PII

• Bad: "Use ~/User/pete/verify_system_integrity.sh", "use the installed docs writing skill and agent-browser cli"

• Good: "Use local tooling such as browser use tools for self-verification"

• Bad: "Ask for Nikita's approval when editing"

• Good: "Avoid editing without contributor approval"

• Bad: "This was committed by pete@kent.sh"

• Good: "" (do not mention)

• Bad: "Use trash for file deletion" (assumes reader is on Mac and has trash installed)

• Good: "" (do not mention duplicate or local-only guidance)

Page patterns

Behavior page

• Short overview.
• How to invoke or use it, but only when syntax alone is insufficient.
• Key semantics and defaults.
• Failure behavior only if operator-relevant.
• One minimal example.

Reference page

• Stable schema or table first.
• Short notes only where needed to prevent misuse.
• Do not re-explain neighboring features at length.

Edit checklist

• Can this sentence survive unchanged six months from now?
• Did I remove process, history, and rollout language?
• Did I duplicate anything already owned elsewhere?
• Does the page stand on its own without see X page?
• Can I delete words without losing meaning?