Working with Documentation

Series: Claude Learning Journey · Intermediate Usage

Documentation is the bridge between what you know and what Claude can work with. The better your docs, the more useful Claude becomes in your project. This is not a coincidence — the process of writing good documentation forces you to clarify decisions, which gives Claude better material to work with.

Most developers treat documentation as a chore. Claude changes the calculus: documentation you write for yourself tomorrow is context you will give Claude in a month. If that documentation is vague, generic, or out of date, you will repeat yourself constantly. If it is precise and honest, Claude will internalise it faster than any human code review.

The Honest README

A README that says “A modern API client for REST services” tells Claude nothing. A README that says “This client wraps the Stripe API with automatic retry logic, token refresh, and a response cache. It assumes a single API key per client instance. We built it because the official SDK did not support our specific retry strategy. Timeout defaults are conservative: 30s for writes, 10s for reads.” gives Claude something real.

The difference is specificity. Specific documentation reflects specific decisions. Specific decisions are what Claude needs to work accurately within your project.

Documenting Decisions, Not Just Outcomes

Most documentation describes what the code does. Great documentation also explains why. Why did you choose this approach? What alternatives were rejected? What constraints shaped the design?

When Claude understands why, it can make consistent choices. Without that context, it might suggest changes that are technically correct but strategically wrong — undoing decisions that were made for reasons not obvious from the code alone.

A decisions log does not need to be formal. A file called DECISIONS.md that records “we chose Postgres over Mongo because we needed relational integrity for billing” is documentation. A comment in the schema that says “denormalised here for query performance, accept the write amplification cost” is documentation.

READMEs That Work for Claude

A README that Claude can use should cover:

1. What the project does, written for someone who has never seen it
2. The core concepts and terminology
3. How to get from zero to a working development environment
4. The main patterns and conventions
5. What the project is explicitly not trying to do

It should not be marketing copy. It should not be a todo list. It should not be a list of features copied from the issue tracker.

Keeping Docs in Sync

Documentation rot is real. Claude makes it worse if you use it carelessly, because it will confidently reference documentation that is out of date. The discipline: when you change behaviour, update the doc first, then the code comment, then ship.

Or at minimum: include a “last reviewed” date in significant docs and treat outdated docs as bugs.

What You’ll Learn

• Why specific documentation beats generic documentation
• How to document decisions, not just outcomes
• What to include in a README that Claude can actually use
• How to keep documentation from going stale

Try It Yourself

Find a project you work on regularly. Open the README and ask: if I gave this to a competent engineer who had never seen this project, could they understand what it does and how to contribute? If not, spend twenty minutes making it more specific. Then ask Claude to read it and describe what the project does — notice where it fills gaps and where it goes wrong.

What’s Next

Documentation connects to version control — the git history of your project is itself a form of documentation. In the next post we will look at how to use Claude productively within a git workflow.

---

Part of the Claude Learning Journey series · Next: Git Workflow: Using Claude with Version Control