Document Generate

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

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:

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

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