How I use Claude Code to write documentation — a complete workflow

Documentation is the task every developer puts off until it's urgent. You have a function that made sense six months ago, a README that hasn't been updated since the initial commit, and an API that's documented in someone's head.

I've been using Claude Code to fix this systematically. Here's the exact workflow.

The documentation debt problem

Undocumented code is a tax. Every new team member, every debugging session, every API consumer pays it. The problem is that writing docs feels slow and unrewarding — until you've lost 3 hours to a function that had no docstring.

The sessions where I'm most likely to hit rate limits aren't the ones where I'm writing new features. They're the ones where I'm reading undocumented legacy code, trying to understand what it does before I can document it.

My workflow

Step 1: Audit what's missing

Find all public functions, classes, and modules in this codebase that are missing docstrings or have docstrings shorter than 2 lines. Return a list sorted by how frequently they're called (most-called first).

This surfaces the highest-value documentation gaps first. A utility function called in 47 places with no docs is more expensive than an endpoint called once.

Step 2: Understand before you document

Read auth.js and explain what each exported function does, what its inputs and outputs are, what errors it can throw, and what side effects it has. Then write JSDoc comments for each one.

The key here: understand first, then document. If you ask Claude Code to write docs without first understanding the function, you get generic descriptions that aren't much better than no docs.

Step 3: README reconstruction

The README is usually the most stale file in any repo. I use this prompt:

Read the entire codebase and write a README that accurately reflects what this project does today (not what it was supposed to do). Include: what it does, how to run it locally, environment variables required, API endpoints, and how to contribute.

This is where the rate limit problem bites hardest. A large codebase means a lot of context. Claude Code reads every relevant file, holds it all in context, then writes the README. Long session = lots of tokens.

Step 4: API documentation

Find all Express routes in this codebase. For each route, document: HTTP method, path, request body schema, response schema, authentication requirements, and example curl command. Output as OpenAPI 3.0 YAML.

This generates machine-readable docs that can plug directly into Swagger UI or Postman.

Step 5: Inline comments for complex logic

Find the 5 most complex functions in this codebase (measured by cyclomatic complexity or length). Add inline comments explaining the non-obvious logic — not what the code does, but why it does it that way.

The "why" is what's actually valuable in comments. Anyone can read that a loop iterates over an array. Almost no one can explain why the array is processed in reverse order.

The rate limit wall

Documentation sessions are some of the longest I run. You're asking Claude Code to read an entire codebase, understand it deeply, and produce structured output. That's a lot of context.

When I hit rate limits mid-session, I lose momentum. The context that took 20 minutes to build up gets interrupted.

I switched to SimplyLouie (✌️2/month) specifically because I kept hitting the official rate limits during documentation sprints. The unlimited-session model means I can do an entire documentation audit in one sitting.

The output

After a documentation session, I typically have:

• Docstrings on all public functions
• An accurate README
• OpenAPI spec for all routes
• Inline comments on complex logic
• A documentation debt log for what's still missing

The last item is important. Perfect documentation isn't the goal — knowing what's undocumented is.

One more thing

Documentation isn't just for other developers. It's for you-in-six-months, who has completely forgotten why you made the choices you did.

The best time to document is right after you write the code. The second best time is now.

---

What's your documentation workflow? What's the worst undocumented codebase you've inherited?