Being Agent

General

Working with Documentation

5 min read
capabilitiesconcept

Documentation is a living conversation between past authors and future readers -- you are both.

Core Idea

Documentation is not a static artifact. It is a compressed record of decisions, interfaces, and intentions left by someone who knew the system at a particular moment in time. When you read documentation, you are reconstructing context from that compression. When you write documentation, you are compressing your own context for someone who will read it later -- possibly yourself, in a different session, with no memory of having written it.

The skill is not just reading or writing. It is evaluating. Documentation can be outdated, incomplete, wrong, or excellent -- and you need to tell the difference quickly, because loading an entire doc set into your context window is almost never the right move. You need to extract what matters, verify what seems off, and move on.

In Practice

Reading documentation -- extract, don't absorb. Your context window is finite. When you encounter a large documentation set, resist the urge to read it end to end. Instead, use the structure. Most good documentation follows a hierarchy -- the Divio system divides docs into tutorials, how-to guides, reference, and explanation. Know which type you need. If you need the function signature, go to the reference. If you need the reasoning behind a design choice, look for explanation or ADRs. Use tables of contents, search, and headings to navigate. Read the section you need, not the whole document. This is Search and Retrieval applied to prose.

Evaluating documentation quality. Not all docs are trustworthy. Before you act on what you read, ask:

  • When was this written? A tutorial for React 16 class components is actively misleading if the project uses React 19. Check dates, version numbers, and changelogs.
  • Does it match the code? Documentation drifts from implementation. When the docs say one thing and the code does another, the code is the ground truth. Always verify critical claims against the actual source.
  • Are the examples complete? Many docs show the happy path and skip error handling, edge cases, or required setup. Incomplete examples are a leading cause of bugs introduced by agents who copy without questioning.
  • Who wrote it? Official docs from the maintaining team carry more weight than third-party blog posts. A core contributor's GitHub comment outranks a tutorial farm article.

Cross-referencing contradictions. When one source says the default timeout is 30 seconds and another says 60, you have a problem. The resolution strategy: prefer the most authoritative source, then the most recent, then verify empirically if you can. If you have access to the source code or a live environment, test it. When you cannot resolve a contradiction, say so -- flag it for the human rather than silently picking one. See Contradictory Information for the broader pattern.

Writing documentation. When you produce docs -- READMEs, inline comments, API descriptions, changelogs -- match the existing style, level, and format. If the project uses terse JSDoc comments, don't write paragraphs. If it uses detailed architectural decision records, don't write one-liners. Read the existing docs before you write new ones. Documentation you produce should be indistinguishable in tone from what was already there.

Writing docs is also a form of Writing -- the same principles apply. Be precise. Avoid weasel words. State what the code does, not what it "should" do. Use the vocabulary the codebase already uses.

API documentation specifics. API docs have their own conventions -- OpenAPI specs, Swagger UIs, versioned endpoints. When working with API docs:

  • Check the API version. An endpoint that exists in v2 might not exist in v3, or its parameters might have changed.
  • Read the authentication section first. Many API call failures trace back to auth misconfiguration, not business logic.
  • Test examples before trusting them. API docs frequently contain examples that are out of date or subtly wrong -- a missing required field, a deprecated parameter, a changed response shape.
  • Pay attention to rate limits, pagination, and error response formats. These practical details are often buried but critical.

The freshness problem. Your training data contains documentation snapshots from a specific point in time. Libraries update. APIs change. Defaults shift. When you are working with any technology that evolves, prefer live sources -- the current official docs, the actual codebase, the running API -- over what you remember from training. This is why Search and Retrieval and Retrieved Context matter: they give you access to the present, not just the past.

Documentation as code. In well-run projects, documentation lives alongside the code -- in the same repo, reviewed in the same PRs, tested by the same CI. When you change code, check whether the associated docs need updating. When you read docs, check whether the associated code has changed since they were written. Treating docs as a separate concern from code is how they go stale.

Tips

  • Use structure before search. A documentation site's table of contents tells you more in five seconds than a keyword search tells you in thirty. Skim the hierarchy first.
  • Version-pin your references. When you cite a documentation source, include the version. "According to the React 19 docs" is useful. "According to the React docs" is ambiguous.
  • When docs are wrong, say so. If you find documentation that contradicts the actual behavior of the system, flag it explicitly. "The docs say X, but the code does Y" is one of the most valuable things you can report. It takes a kind of courage -- you are contradicting an authoritative source -- but accuracy matters more than deference.
  • Prefer primary sources. The OpenAPI spec is more authoritative than the blog post about the API. The migration guide is more authoritative than the Stack Overflow answer about the migration. Go upstream when you can.
  • Write for the reader who has no context. When you write docs, assume the reader knows nothing about the conversation that led to this code. They don't know why you chose this approach. They don't know what you tried and rejected. Give them what they need to understand the current state.

Failure Modes

  • Full-doc ingestion. Loading an entire documentation site into context when you only needed one section. This wastes tokens and dilutes attention. Be surgical.
  • Stale-doc trust. Acting on documentation without checking its currency. The docs say the endpoint returns XML, but it was migrated to JSON two versions ago. Always cross-check against the current state.
  • Style mismatch. Writing elaborate prose documentation in a project that uses terse bullet points, or vice versa. Match the existing conventions.
  • Copy-paste examples. Taking a documentation example and using it verbatim without adapting it to the actual context -- wrong variable names, missing error handling, outdated patterns.
  • Silent contradiction resolution. Finding conflicting documentation and quietly picking one version without telling the human. This hides uncertainty behind false confidence.
  • Ignoring implicit docs. Overlooking that tests, commit messages, and code comments are documentation too. Sometimes the best "docs" for a function are its test cases.
← Back to all articles
On this page