Technical Documentation

Documents and decksevalv1.0.1released 2026-07-25

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: step-0. Each step names the specialist role it wants; the full working prompt is expandable.

Step 0: Scope & Intentplannerentry

Show working prompt

1. Determine what to document:
   - **If invoked with a specific target** (feature, module, file, skill): scope is that target
   - **If invoked for an entire project**: scope is the full project
   - **If called from /document-release with gaps**: scope is the specific entities from the coverage map

2. Use AskUserQuestion to confirm scope and ask about documentation target:

   - A) Write documentation inline in existing files (README, ARCHITECTURE, etc.)
   - B) Create standalone documentation files (e.g., `docs/` directory)
   - C) Both — inline summaries in existing files + deep docs in standalone files

   RECOMMENDATION: Choose C because it maximizes both discoverability and depth.

3. Determine the output format:
   - If the project already has a `docs/` directory, follow its conventions
   - If the project uses a doc framework (Nextra, Docusaurus, MkDocs, VitePress), follow its format
   - Otherwise, use plain Markdown files in `docs/`

---

Record the scope decision in docs/plan.md: what is being documented, for whom, and which Diataxis quadrants each target gets.

Step 1: Codebase Archaeology (Research Phase)developer

Show working prompt

**This is the most important step.** Do not skip or rush it. The quality of your documentation
is directly proportional to how well you understand the code.

1. **Map the project structure:**

2. **Read the entry points.** Identify and read:
   - README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md / AGENTS.md
   - package.json / Cargo.toml / pyproject.toml / go.mod (understand the project type)
   - Main entry files (index.ts, main.rs, app.py, cmd/main.go)
   - Configuration files and examples

3. **Read the source code for each target entity.** For each feature/module you're documenting:
   - Read the implementation files end-to-end (not just signatures)
   - Read the tests — they reveal intended behavior, edge cases, and usage patterns
   - Read related modules that the target depends on or is depended upon by
   - Read any existing inline comments, especially `// NOTE:`, `// DESIGN:`, `// WHY:`

4. **Build a concept map.** Before writing, produce an internal outline:

```
Target: [feature/module name]
Purpose: [one sentence — what problem does it solve?]
Key concepts: [list the 3-5 concepts a reader must understand]
Public surface: [commands, functions, config options, API endpoints]
Dependencies: [what it needs from other modules]
Dependents: [what relies on it]
Edge cases: [from reading tests and code]
Design decisions: [any non-obvious "why" choices]
```

5. Output: "Researched N files, identified K public surface items, M concepts, and J design decisions."

---

Capture the map under an '## Architecture notes' section in docs/plan.md — entry points, core modules, and the flows the docs must explain.

Step 2: Diataxis Partitioningplanner

Show working prompt

For each target entity, decide which Diataxis quadrants to produce. Not every entity needs all four.

**Decision matrix:**

| Entity type | Tutorial? | How-to? | Reference? | Explanation? |
|---|---|---|---|---|
| New feature a user interacts with | ✅ | ✅ | ✅ | Maybe |
| CLI command or flag | Maybe | ✅ | ✅ | No |
| Internal module/architecture | No | No | ✅ | ✅ |
| Config option | No | ✅ | ✅ | No |
| Design pattern / philosophy | No | No | No | ✅ |
| API endpoint | Maybe | ✅ | ✅ | No |
| Workflow (multi-step process) | ✅ | ✅ | No | Maybe |

Output the partition plan:

```
Documentation plan:
  [entity]              [tutorial] [how-to] [reference] [explanation]
  Widget system         ✅ new     ✅ new   ✅ new      ✅ new
  --verbose flag        ❌        ✅ new   ✅ inline   ❌
  Bayesian scheduler    ❌        ❌       ✅ new      ✅ new
```

If the plan has more than 5 documents to create, use AskUserQuestion to confirm before proceeding.
For smaller scopes, proceed directly.

---

Add the decision matrix as a '## Diataxis plan' table in docs/plan.md.

Step 3: Write Reference Documentation Firstcopywriter

Show working prompt

Reference docs are the foundation. They are factual, complete, and derived directly from code.
Write these before tutorials or how-tos because they establish the vocabulary.

**Reference doc template:**

```markdown
# [Entity Name]

[One paragraph: what it is, what it does, when you'd use it.]

## API / Interface

[Complete listing of public surface: functions, commands, config options, parameters.
Include types, defaults, and constraints. Pull directly from code — do not paraphrase
loosely.]

## Options / Configuration

[If applicable: every option with its type, default, and effect.]

## Examples

[2-3 concrete examples showing actual usage. Prefer real command output or code that
would actually compile/run.]

## Related

[Links to other reference docs, how-tos, or explanations that provide context.]
```

**Rules for reference docs:**
- Accuracy over elegance. Every claim must be traceable to code.
- Include types, defaults, and constraints. "Accepts a string" is insufficient — "Accepts a
  string (max 256 chars, must match `^[a-z-]+$`)" is reference-grade.
- Show real examples that would actually work if copy-pasted.
- Do not explain *why* — that belongs in explanation docs.

---

Write each reference document under docs/reference/.

Step 4: Write Explanation Documentationcopywriter

Show working prompt

Explanation docs answer "why does this work this way?" They are the design rationale.

**Explanation doc template:**

```markdown
# [Concept / Design Decision]

[Opening paragraph: the problem this design solves, stated in terms a smart reader
who hasn't seen the code would understand.]

## The problem

[Concrete description of what goes wrong without this design. Real failure modes,
not abstract risks.]

## The approach

[How the design solves the problem. Include diagrams (ASCII or Mermaid) for
architectural concepts.]

## Trade-offs

[What was given up. Every design decision trades something — name it explicitly.]

## Alternatives considered

[If discoverable from code comments, ADRs, or git history: what was tried or
rejected and why.]
```

**Rules for explanation docs:**
- Lead with the problem, not the solution.
- Use ASCII diagrams for architecture. They're grep-able, diff-friendly, and render everywhere.
- Name trade-offs explicitly. "We chose X over Y because Z" is the gold standard.
- Do not repeat reference material — link to it.

---

Write each explanation document under docs/explanation/.

Step 5: Write How-To Guidescopywriter

Show working prompt

How-tos are task-oriented. They assume the reader knows the basics and wants to accomplish
something specific.

**How-to doc template:**

```markdown
# How to [accomplish specific task]

[One sentence: what you'll accomplish and the end result.]

## Prerequisites

[What the reader needs before starting. Be specific — versions, installed tools,
config state.]

## Steps

1. [Action verb] [specific instruction]

   ```bash
   [exact command]
   ```

   [Expected output or result, if non-obvious.]

2. [Next step...]

### Verification

[How to confirm it worked. A command, a URL to visit, a test to run.]

### Troubleshooting

[Common failure modes and their fixes. Pull from tests and error handling code.]
```

**Rules for how-to docs:**
- Title starts with "How to" — no exceptions. This is the reader's entry point.
- Every step must be actionable. No "consider whether..." — instead "Run X" or "Add Y to Z".
- Include verification. The reader should never wonder "did it work?"
- Troubleshooting section is mandatory if the task can fail.

---

## Step 6: Write Tutorials

Tutorials are learning-oriented. They take a newcomer from zero to a working example.
These are the hardest to write well and the most valuable.

**Tutorial doc template:**

```markdown
# [Tutorial title — describes what you'll build/learn]

[Opening paragraph: what you'll build, why it's useful, and what you'll understand
by the end. Keep it concrete — "You'll build a working X that does Y" not
"This tutorial covers X".]

## What you'll need

[Prerequisites: tools, versions, prior knowledge. Link to installation guides.]

## Step 1: [Set up the foundation]

[Start from a clean state. Show every command. Explain what each does on first
encounter — but briefly, not a lecture.]

```bash
[exact command]
```

[Brief explanation of what just happened.]

Write each how-to guide under docs/how-to/.

Evaluatereviewer

Show working prompt

Read docs/plan.md and spot-check each produced document against the code it describes: are the reference pages factual, do the how-tos actually work, is anything in the Diataxis plan still missing? If a quadrant is missing or wrong, loop back to Step 3 and fill it. Otherwise advance to Finish. Routing: ALL criteria pass → advance to finish; ANY criterion fails → loop back to step-3 with a note naming the exact gap.

Finishdeveloper

Show working prompt

Summarize what was documented and where it lives (the docs/ tree), and hand back to the user. Write a one-paragraph DONE summary to task notes via `write_task_note`, then report DONE.

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