| name | edit-the-docs |
| description | Restructure, reorder, and improve existing Supabase docs pages under apps/docs — clarity, connective text, section grouping, and brevity. Use when asked to edit, reorganize, restructure, tighten prose, or add glue between sections on a page that already exists. Not for net-new feature drafts (use write-the-docs) or PR triage/verification (use review-the-docs). |
Edit the docs
Improves existing Supabase docs pages: structure, order, connective text,
and clarity. Distinct from write-the-docs
(draft net-new or product-grounded rewrites from intent + code) and
review-the-docs (lint, build, PR triage).
Core rules
- Read before you rewrite. Open the target page and nearby pages of the same type. Name the reader's goal and the page type (explainer, guide, tutorial, troubleshooting) before moving sections.
- Improve structure and clarity; don't invent product truth. Preserve behavior claims, UI labels, and positioning unless you verify a change against code or product intent. Accuracy gaps or missing net-new content belong with
write-the-docs / pm-the-docs, not silent invention here.
- Follow CONTRIBUTING.md and WORD_LIST.md for voice, terminology, and formatting. See
apps/docs/CONTRIBUTING.md and apps/docs/WORD_LIST.md.
- Prefer brevity. Prefer broad strokes when mechanical detail doesn't help the reader's task. Cut redundancy; don't over-explain.
- Reuse sibling skills. IA/architecture via
ask-the-docs; validation and self-review via review-the-docs. Shared pitfalls live in write-the-docs/reference/common-pitfalls.md — apply them, don't duplicate them.
Phase 1 — Diagnose
- Identify the document type per CONTRIBUTING.md (explainer, tutorial, guide, reference, or troubleshooting).
- State the reader's goal and prerequisites in one or two lines.
- Note structural problems: mixed information types interrupting a procedure, missing intro navigation on a long page, weak transitions, redundancy, or over-explained mechanics.
- Summarize the diagnosis to the requester before large moves when the restructure would change how the page is read.
Phase 2 — Restructure
Apply the Mixed information types, Navigation, and Cross-references and glue guidance in apps/docs/CONTRIBUTING.md (Guides section), summarized here:
- Classify substantial sections as contextual, procedural, or reference content. In a mixed page, group sections by information type so that context doesn't interrupt the procedural path.
- For a long or mixed page, add a short introduction that links to its major section groups and tells readers when to use each one. Skip this navigation when a short page is already easy to scan.
- Connect contextual sections to their corresponding procedures when useful. Add introductions to section groups, transitions between information types, and outcomes after procedures. Don't link every adjacent section.
- Move and regroup first; preserve meaning. Don't silently rewrite facts while restructuring.
Phase 3 — Edit for clarity
- Use second person, present tense, short paragraphs, and ordered steps for sequential actions.
- Cut restated points and mechanical over-explanation.
- Apply
write-the-docs/reference/common-pitfalls.md: timelessness, no internal planning context in shipped MDX, redundancy, single-item lists, admonition restatement.
- Search
apps/docs/WORD_LIST.md when introducing or revising technical terms and UI actions.
- Keep code samples executable in their stated context; mark intentionally omitted code. Prefer partials under
apps/docs/content/_partials/ over copied blocks.
Phase 4 — Validate
Before handoff:
Mechanics (anchors, lint, format): follow write-the-docs/reference/drafting-mechanics.md. Before renaming or rewording headings, grep for #<old-anchor-slug> under apps/docs/content and update matches.
Then run review-the-docs local self-review (pnpm lint:mdx, and pnpm build:guides-markdown when guides/explainers/tutorials changed).
Additional resources
