Technical Documentation
Generate a coherent documentation set from a codebase, organized by the Diataxis model (tutorials, how-to guides, reference, explanation), with cross-links and a coverage pass.
Steps
Entry step: inventory. Each step names the specialist role it wants; the full working prompt is expandable.
- Inventory the documentation surfacetechnical researcherentry
Map readers, public interfaces, source evidence, existing coverage, and gaps.
Show working prompt
Confirm the requested scope from the task and project context. Inspect the project guide, package or build metadata, entry points, public interfaces, configuration, examples, tests, and current docs with workspace tools. Build an exact inventory of the entities in scope, their source paths, intended readers, existing documentation, missing coverage, and risky claims that need verification. Do not start polished prose yet. Observable handoff: write the completed result to `notes/documentation-inventory.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
- Design the documentation setdocumentation architect
Choose the right document type for each reader need and lock verification criteria.
Show working prompt
Turn `notes/documentation-inventory.md` into a document plan. For each proposed page, state its reader, job, quadrant, destination path, evidence sources, prerequisites, cross-links, and pass/fail checks. Reuse existing conventions and update existing pages when that is clearer than duplication. Keep the set proportional to the scope, but cover every public item in the inventory or explicitly defer it with a reason. Before working, open `notes/documentation-inventory.md` with `read_artifact`. Observable handoff: write the completed result to `notes/documentation-plan.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
- Author, link, and verify the docstechnical writer
Write the planned pages, validate examples and links, and expose the complete set through one index.
Show working prompt
Implement the approved document plan in the workspace. Keep reference factual, how-to steps actionable, tutorials quick to first result, and explanations explicit about trade-offs. Verify commands, code examples, option names, defaults, and constraints against implementation and tests; run safe examples where possible and label anything not executed. Add troubleshooting based on real failure paths. Cross-link related pages and write an index that lists every created or updated document, its reader job, quadrant, source evidence, and verification status. Observable handoff: write the completed result to `docs/documentation-index.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.
- Evaluate the deliverabletechnical editor
Independently grade the observable deliverable and route it to finish, repair, or user escalation.
Show working prompt
Review `docs/documentation-index.md`, `notes/documentation-inventory.md`, `notes/documentation-plan.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone. 1. Every in-scope public item is documented or explicitly deferred with a reason. 2. Claims, types, defaults, constraints, and examples agree with the cited implementation or tests. 3. Tutorial, how-to, reference, and explanation content serve distinct reader jobs without needless duplication. 4. Commands and examples have credible verification results or are clearly marked unexecuted. 5. Every produced page is linked from the index and all internal links resolve. 6. The prose is concrete, readable, and includes real troubleshooting and trade-offs where relevant. Open `notes/documentation-inventory.md`, `notes/documentation-plan.md` with `read_artifact`. Open `docs/documentation-index.md` with `read_file`. Write the evidence-backed review to `reviews/technical-documentation-review.md` in the artifacts drawer with `write_artifact`. Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. Then use `advance_task_step` for the active task: PASS routes to `finish`; REVISE routes to `repair` for review rounds 1 through 2, and the 3th REVISE routes to `needs-user`. Never route to finish while a criterion is unmet.
- Repair the deliverabletechnical writer
Fix only the concrete gaps from the latest independent review.
Show working prompt
Read `reviews/technical-documentation-review.md` with `read_artifact` and repair every failed criterion in `docs/documentation-index.md`, `notes/documentation-inventory.md`, `notes/documentation-plan.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `docs/documentation-index.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.
- Finishproject lead
All deterministic and reviewer criteria passed.
Show working prompt
The independent review passed. Read `reviews/technical-documentation-review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`docs/documentation-index.md`, `notes/documentation-inventory.md`, `notes/documentation-plan.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.
- Escalate unresolved concernsproject lead
The bounded repair loop ended without a defensible pass.
Show working prompt
The deliverable did not pass after 3 review rounds. Do not claim success. Read `reviews/technical-documentation-review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.
Triggers
Phrases that suggest this craftbook to a crew.
- write docs for this
- generate documentation
- document this feature
- create a tutorial
- write a how-to
- explain this module
- docs for this project
Source
View this craftbook on GitHub · MIT license