Document Generate

Document Generate creates missing documentation for a codebase from the implementation up. It is for greenfield documentation coverage, not small doc touch-ups.

The organizing frame is Diataxis:

• Tutorial - get to a first successful result
• How-to - complete a specific task
• Reference - factual interface details
• Explanation - why the design works this way

When to Use

• A shipped feature has little or no documentation
• A module or subsystem needs first-pass docs from the source code
• A project needs documentation coverage beyond one README paragraph
• You need to decide which entities deserve tutorial, how-to, reference, and explanation docs

When NOT to Use

Instead of document-generate	Use
Updating docs after a code change	doc-update
Generating only deep API or interface reference docs, with no tutorial/how-to/explanation coverage	api-documentation
Creating VS Code CodeTour onboarding files	code-tour

Workflow

1. Define the scope and output mode

Choose one:

• one feature
• one module
• one subsystem
• the whole project

Then choose where the docs should land:

• inline updates to existing docs
• standalone docs in docs/
• both

If the scope is large, recommend starting with one feature or module first.

2. Do codebase archaeology before writing

Read enough source to understand reality:

• entry points and exported surface
• implementation files
• tests
• README, architecture docs, and contribution docs
• comments that explain design intent

The point is to document the code that exists, not the code you assume exists.

3. Partition the surface with Diataxis

Not every entity needs all four document types.

Use this rule of thumb:

Entity type	Tutorial	How-to	Reference	Explanation
End-user feature	Maybe	Yes	Maybe	Yes
CLI flag or config option	No	Yes	Yes	No
Public API or interface	No	Maybe	Yes	Maybe
Internal design concept	No	No	Maybe	Yes

Write down the coverage plan before generating files.

4. Write reference first

Reference documentation sets the vocabulary for the rest:

• names
• signatures
• defaults
• allowed values
• examples

Keep it factual. If you want to explain why something exists, that belongs in the explanation doc.

5. Write explanation second

Capture:

• the problem being solved
• the chosen design
• tradeoffs
• rejected alternatives
• operational or maintenance implications

Explanation tells future readers why the current shape is reasonable.

6. Write how-to guides for concrete tasks

A how-to guide should include:

• prerequisites
• exact steps
• expected result
• verification
• troubleshooting

It should help an experienced user accomplish one specific job.

7. Write tutorials for the first successful outcome

Tutorials are for first success, not exhaustive coverage.

Good tutorial rules:

• target one happy-path outcome
• keep the step count low
• end with "what you built" or equivalent payoff
• link out to reference docs for deeper detail

8. Cross-link for discoverability

Make the docs navigable:

• tutorial -> how-to/reference
• how-to -> reference
• explanation -> reference and related concepts
• README or index -> newly created docs

9. Run a quality review before stopping

Check:

• no broken links
• no duplicate docs saying the same thing
• the docs reflect current behavior
• each document has one clear job

Output Template

## Documentation Plan

| Entity | Tutorial | How-to | Reference | Explanation |
|--------|----------|--------|-----------|-------------|
| ... | ... | ... | ... | ... |

## Generated Files

- path - quadrant - purpose

## Coverage Gaps

- ...

Common Rationalizations

Rationalization	Reality
"README is enough."	A README cannot carry tutorial, task guide, reference, and design rationale all at once.
"I'll just write the API docs."	Users also need onboarding and task-level guidance.
"Docs can be added later."	The source context is clearest while the feature is still fresh.

Red Flags

• Writing docs from filenames without reading implementation
• Repeating the same content in tutorial, how-to, and explanation
• Treating reference docs like narrative essays
• Ending without updating discoverability links

Verification

• The source code and tests were read before drafting
• Each generated doc has a clear Diataxis role
• document-generate is not being used for a small incremental doc sync
• document-generate is not being used for API-only reference work that belongs in api-documentation
• Cross-links and index or README discoverability were updated

See Also

• doc-update - sync existing docs after code changes
• api-documentation - write API and interface reference docs from source
• architecture-decisions - capture hard-to-reverse design choices as ADRs