public-docs

by sentry

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…

npx skills add https://github.com/getsentry/junior --skill public-docs

Download ZIP GitHub

336

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)