Essential session storage is required to sign in. Optional analytics remain off unless you allow them.
Produce documentation for a real API or SDK to a professional bar. Include: (1) a fast QUICKSTART that gets a developer to first success quickly; (2) conceptual guides, task how-tos, and a complete REFERENCE; (3) runnable CODE SAMPLES (ideally in 2+ languages) that are TESTED in CI so they can't rot; (4) authored docs-as-code with a static site generator, versioning, and a style guide enforced by a linter (Vale); (5) accessibility (heading hierarchy, alt text, link text) and localization-readiness; and (6) at least one diagram authored as diagrams-as-code (Mermaid/PlantUML). Define how you'd MEASURE the docs (failed searches, feedback, time-to-first-success) and keep them current.
A quickstart that minimizes time-to-first-success plus complete reference/guides; the doc set is something a developer could actually build with.
Runnable code samples tested in CI (won't rot); Markdown + SSG + versioning; style enforced by a linter.
Accessible structure (headings/alt text/link text), localization-ready writing, and at least one diagrams-as-code diagram.
A concrete plan to measure docs (failed searches/feedback/task success) and keep them current with the product.
Use this README structure to make the work reviewable.
DevPath fetches a read-only, size-capped snapshot. Submitted code is never executed.
# Production-quality developer docs with tested samples ## Goal Produce documentation for a real API or SDK to a professional bar. Include: (1) a fast QUICKSTART that gets a developer to first success quickly; (2) conceptual guides, task how-tos, and a complete REFERENCE; (3) runnable CODE SAMPLES (ideally in 2+ languages) that are TESTED in CI so they can't rot; (4) authored docs-as-code with a static site generator, versioning, and a style guide enforced by a linter (Vale); (5) accessibility (heading hierarchy, alt text, link text) and localization-readiness; and (6) at least one diagram authored as diagrams-as-code (Mermaid/PlantUML). Define how you'd MEASURE the docs (failed searches, feedback, time-to-first-success) and keep them current. ## Acceptance criteria - [ ] Developer experience: A quickstart that minimizes time-to-first-success plus complete reference/guides; the doc set is something a developer could actually build with. - [ ] Tested samples & docs-as-code: Runnable code samples tested in CI (won't rot); Markdown + SSG + versioning; style enforced by a linter. - [ ] Accessibility & visuals: Accessible structure (headings/alt text/link text), localization-ready writing, and at least one diagrams-as-code diagram. - [ ] Measurement & upkeep: A concrete plan to measure docs (failed searches/feedback/task success) and keep them current with the product. ## Verification - [ ] Document installation and run commands. - [ ] Record automated checks and their exact commands. - [ ] Add representative output, screenshots, or a short demo where useful. - [ ] Confirm failure paths and known constraints. ## Decision log ### Decision title - Context: - Choice: - Alternatives considered: - Tradeoffs: ## Evidence - Link each rubric criterion to the file, test, or artifact that demonstrates it. ## Known limitations - List what is intentionally out of scope and what should be improved next.