How-to: Create docs with Claude Code, step by step

By Git2Docs Founders

This is a hands-on guide to creating docs with Claude Code: what to set up, what to ask, and how to check the output before anyone else reads it.

If you’re still deciding whether Claude is the right way to document your product at all, start with Can Claude write your docs? What works, and where it breaks. This guide picks up once you’ve decided to try it.

What you’ll need:

• Claude Code installed, with access to your repo
• A way to run your software, locally or on a staging environment, so examples can be tested
• Test credentials for that environment, never production keys
• A clear idea of who will read the docs

How to create docs with Claude Code

These eight steps expand the six-step DIY workflow on our Claude for docs page, with the prompts, files, and checks for each one. Steps 1 to 7 produce your first set of docs. Step 8 keeps them current.

Step 1: Define the scope and audience

Before you open a terminal, decide what you’re documenting and for whom. A README for contributors, a getting-started guide for new users, and an API reference for integrators need different depth and tone. Write it down in a sentence or two, for example: “Public REST API reference for external developers, plus a quickstart.” Clear scope does more for output quality than any prompt trick.

Step 2: Open the repo in Claude Code and set up CLAUDE.md

Run Claude Code from your repo root and use /init to draft a CLAUDE.md file. Then add a documentation section that covers:

• Audience and reading level
• Voice and tone, such as short sentences, second person, no marketing language
• Product terms and how to spell them
• Where docs live (for example, docs/) and the format, Markdown or MDX
• What to leave out, such as internal modules or deprecated endpoints

Here’s a starting point you can paste in and edit:

## Documentation
- Audience: developers integrating with our public REST API. Assume they know HTTP and JSON, not our internals.
- Voice: second person, present tense, short sentences. No marketing language.
- Terms: "workspace" (never "project"), "API key" (never "token").
- Location: docs/ as Markdown, one file per page. Reference pages go in docs/api/.
- Page template: docs/TEMPLATE.md.
- Leave out: anything under src/internal/ and endpoints marked @deprecated.
- Examples: every example must run as written against a local dev server.

Claude reads this file at the start of every session, so it’s how you keep tone and terms consistent from page to page.

Step 3: Map the public surface before writing

Don’t start with “write the docs.” First ask Claude to inventory what needs documenting: endpoints, CLI commands and flags, configuration options, environment variables, and public classes. Plan mode helps here, because Claude explores and proposes without editing files. Review the list, cut anything internal, and save it as an outline (for example, docs/OUTLINE.md) that every later prompt references.

A prompt that works well:

List every public endpoint, CLI command and flag, configuration option, and environment variable in this repo. Group them by area, note the source file for each, and flag anything that looks internal. Don’t write any docs yet.

This list is also your yardstick. Without it, you can’t tell later how much of the product is actually documented.

Step 4: Generate page by page

Work through the outline one page or module at a time. First save a page template, for example docs/TEMPLATE.md, so every page has the same shape:

# Page title
One sentence on what this does and when you'd use it.

## Before you start
Prerequisites, permissions, and versions.

## Example
A complete, copy-paste example that runs as written.

## Parameters
| Name | Type | Required | Default | Description |

## Response
The response shape, with an example.

## Errors
Common errors, what causes them, and how to fix them.

Then point each prompt at the outline, the template, and the source:

Using docs/OUTLINE.md and the conventions in CLAUDE.md, write docs/api/repositories.md covering every endpoint in src/routes/repos.ts. Follow docs/TEMPLATE.md and include one curl example per endpoint.

Review the first page or two closely before you generate the rest. Fixing the template early is far cheaper than fixing twenty pages later. On large codebases, start a fresh session for each area or use subagents, so each pass stays focused on the code it’s documenting.

Step 5: Verify every example against running software

This is the step that separates useful docs from plausible ones. Start the app locally or point at staging, then ask Claude to run each documented command and API call and report anything that fails or behaves differently from what the page says. Fix the page, re-run, and repeat until nothing fails. Keep a record of what was checked, because you’ll need it next release.

A prompt that works well:

Start the dev server. For every command and API call in docs/api/, run it exactly as written and compare the result to what the page says. List each mismatch with the page, the documented behavior, and the actual behavior. Don’t change any files yet.

Before you call a page done, check that:

• Every example runs as written, with no edits
• Parameter names, types, and defaults match the code
• Response examples match what the software actually returns
• Error messages and codes are real
• Nothing depends on data or credentials only you have

Step 6: Review for consistency and gaps

Ask Claude to compare the finished pages against the outline and CLAUDE.md, looking for missing pages, inconsistent terms, broken internal links, and parameters that exist in code but not in the docs. Then have a person skim for tone and for anything that shouldn’t be public.

Step 7: Commit and publish

Commit the docs on a branch and open a pull request, so docs get the same review as code. Then publish them, whether that’s Markdown rendered on GitHub, a static site generator, or a hosted docs platform.

Step 8: Repeat on every release

Docs start drifting with the next merge. After each release, give Claude the diff since the last tag (for example, git diff v1.4.0..v1.5.0) and ask which pages are affected. Regenerate those pages, then run steps 5 and 6 again. You can script parts of this with Claude Code’s non-interactive mode in CI, but someone still has to own the review, the verification, and the publish.

A prompt for the release pass:

Here’s the diff since v1.4.0. List every page in docs/ whose content is affected and explain why. Don’t edit anything yet.

After your first release

Follow these steps and your first set of docs will be good. The harder part starts with the next release. Every merge can change a parameter, a default, or a command, and nothing in your build fails when a page goes stale. Step 8 handles that, but it’s a recurring job someone has to own.

Before you commit to running it by hand, take the five-minute self-check. Five questions about accuracy, coverage, and ownership tell you whether a DIY process will hold up as you ship. For the full picture of where it strains, and what changes once customers and agents rely on your docs, read Can Claude write your docs? What works, and where it breaks.

Frequently asked questions

Already have docs from Claude?

Find out how accurate they are. Git2Docs works alongside Claude Code: point it at one repo and see accuracy and coverage for the docs you have now. 30-day free trial, no card required.