Public Docs
Use this workflow to produce docs that are crisp, task-oriented, and trustworthy for external users.
Load only the references needed for the request:
| Task |
Read |
| Understand docs app layout and constraints |
references/api-surface.md |
| Draft or revise common docs pages |
references/common-use-cases.md |
| Diagnose docs quality/build failures |
references/troubleshooting-workarounds.md |
Core invariants
- Keep docs audience-facing: explain user outcomes, not internal implementation chatter.
- Match the local docs contract in
packages/docs/src/content/docs/contribute/documentation-guidelines.md.
- For new or substantially edited pages, require frontmatter fields:
type, summary, prerequisites, related.
- Include concrete verification steps for tutorial/troubleshooting content.
- End each page with an explicit "next step" path through internal links.
- Prefer minimal runnable examples over long conceptual exposition.
- Keep prose present around lists; avoid heading-plus-bullets-only sections.
Workflow
1. Classify the request
Select one primary path:
- New page authoring
- Existing page refactor/clarification
- Information architecture update (sidebar/redirects/navigation)
- Docs quality pass (accuracy, scannability, consistency)
- Troubleshooting/build-fix for docs app
2. Gather local context
- Read
packages/docs/src/content/docs/contribute/documentation-guidelines.md.
- Read neighboring docs in the same section (
start-here, concepts, extend, operate, reference, contribute).
- If navigation is involved, read
packages/docs/astro.config.mjs (sidebar and redirects).
- If public interfaces are involved, verify the exported TypeScript surface and its code comments directly.
3. Author or edit with the right page shape
- Pick doc
type (conceptual, tutorial, reference, troubleshooting) from intent.
- Follow depth and section guidance from documentation guidelines.
- Keep wording direct and plain; remove filler or internal-only caveats.
- Use titled code fences for file snippets.
- Prefer internal links that advance the reader to the next concrete action.
4. Validate changes
Run the narrowest meaningful checks:
pnpm docs:check
When structure, sidebar, or redirects change, also run:
pnpm docs:build
5. Report completion
Return:
- Changed files and what each change improves for readers
- Validation commands executed and outcome
- Residual risks (for example, missing screenshots, unverified env-specific setup)
1---2name: public-docs3description: Create and maintain public, user-facing product documentation for this repo's `packages/docs` app. Use when asked to write, revise, or review docs pages (tutorial/concept/reference/troubleshooting), improve docs information architecture, fix docs frontmatter/linking issues, or align docs quality with Vercel/Sentry-style standards.4---56# Public Docs78Use this workflow to produce docs that are crisp, task-oriented, and trustworthy for external users.910Load only the references needed for the request:1112| Task | Read |13|------|------|14| Understand docs app layout and constraints | `references/api-surface.md` |15| Draft or revise common docs pages | `references/common-use-cases.md` |16| Diagnose docs quality/build failures | `references/troubleshooting-workarounds.md` |1718## Core invariants19201. Keep docs audience-facing: explain user outcomes, not internal implementation chatter.212. Match the local docs contract in `packages/docs/src/content/docs/contribute/documentation-guidelines.md`.223. For new or substantially edited pages, require frontmatter fields: `type`, `summary`, `prerequisites`, `related`.234. Include concrete verification steps for tutorial/troubleshooting content.245. End each page with an explicit "next step" path through internal links.256. Prefer minimal runnable examples over long conceptual exposition.267. Keep prose present around lists; avoid heading-plus-bullets-only sections.2728## Workflow2930### 1. Classify the request3132Select one primary path:3334- New page authoring35- Existing page refactor/clarification36- Information architecture update (sidebar/redirects/navigation)37- Docs quality pass (accuracy, scannability, consistency)38- Troubleshooting/build-fix for docs app3940### 2. Gather local context41421. Read `packages/docs/src/content/docs/contribute/documentation-guidelines.md`.432. Read neighboring docs in the same section (`start-here`, `concepts`, `extend`, `operate`, `reference`, `contribute`).443. If navigation is involved, read `packages/docs/astro.config.mjs` (`sidebar` and `redirects`).454. If public interfaces are involved, verify the exported TypeScript surface and its code comments directly.4647### 3. Author or edit with the right page shape48491. Pick doc `type` (`conceptual`, `tutorial`, `reference`, `troubleshooting`) from intent.502. Follow depth and section guidance from documentation guidelines.513. Keep wording direct and plain; remove filler or internal-only caveats.524. Use titled code fences for file snippets.535. Prefer internal links that advance the reader to the next concrete action.5455### 4. Validate changes5657Run the narrowest meaningful checks:5859```bash60pnpm docs:check61```6263When structure, sidebar, or redirects change, also run:6465```bash66pnpm docs:build67```6869### 5. Report completion7071Return:72731. Changed files and what each change improves for readers742. Validation commands executed and outcome753. Residual risks (for example, missing screenshots, unverified env-specific setup)
Sentry