HN Debrief

Programmers will document for Claude, but not for each other

  • AI
  • Developer Tools
  • Programming
  • Productivity
  • Management

The post points at a real shift in engineering practice: work that used to feel like thankless overhead, writing specs, overviews, setup notes, decision docs, and feature explanations, suddenly feels worth doing when a coding agent can turn that text into better code right away. Readers did not treat this as hypocrisy so much as a change in incentives. Human-facing docs are expensive because they have to teach background, anticipate different mental models, survive judgment about tone and completeness, and still often get ignored in favor of a quick Slack message or meeting. Agent-facing docs are cheaper, rougher, and immediately useful. You can dump context in ugly prose, get better output, and see the payoff in minutes.

If you want documentation to improve team performance, fix the retrieval and reading culture around it instead of just demanding more writing. Treat agent-facing docs as a forcing function to tighten human docs too, but put guardrails in place so AI-generated notes do not become stale sludge in the repo.

Discussion mood

Mostly positive about writing more documentation for AI workflows, but frustrated and a little bitter about why it took AI to make documentation feel worthwhile. The strongest emotions were resentment that humans do not read docs, skepticism about AI-generated doc slop going stale, and recognition that incentives and team culture, not programmer virtue, decide whether documentation survives.

Key insights

  1. 01

    Reading culture has to be enforced

    Documentation starts working when teams make “show me where you looked” the entry ticket for help. That turns docs from passive clutter into part of the workflow, reveals missing cross-links, and trains people to contribute fixes instead of routing every question through the team historian.

    Make support requests include a doc link or search query. Then reward doc maintenance in reviews, or the same few people will stay trapped as human indexes.

      Attribution:
    • scottlamb #1 #2
    • christoff12 #1
  2. 02

    Temporary planning docs should not become permanent records

    Design docs and plan files help agents implement work, but keeping every generated artifact in the repo quickly creates a graveyard of outdated context. The better pattern was to delete transient plans after completion, salvage the durable parts into canonical docs, and keep reference material near the code so drift is easier to catch.

    Separate working memory from lasting documentation. Keep only docs someone will maintain, and add a drift check in review or CI if you expect them to stay trustworthy.

      Attribution:
    • skybrian #1
    • matheusmoreira #1 #2
    • docheinestages #1
    • binaryturtle #1
  3. 03

    The payoff is immediate enough to change behavior

    People finally write specs because the feedback loop is brutal and clear. Better context produces better code now, not as some vague future team benefit. Several commenters said spending hours building reusable prompts, review skills, or issue-finding agents was worth it because the gain compounds across projects and shows up in the same week.

    Treat documentation work like tool-building. Invest where the same context, review pattern, or spec format will be reused often enough to amortize the setup cost.

      Attribution:
    • cush #1
    • jillesvangurp #1
    • gonzalohm #1
    • matheusmoreira #1
  4. 04

    Agent success is a useful doc quality test

    When people cannot find the right doc, or the doc assumes too much background, they ask humans instead. Coding agents expose the same failure more bluntly. If the model cannot answer from the available material, that often means the docs are hard to discover, written for the wrong mental model, or missing the exact steps people need rather than just an API catalog.

    Test docs by asking whether a newcomer, human or agent, can solve a real task from them. Optimize for findability and task completion, not just completeness.

      Attribution:
    • qsera #1
    • socalgal2 #1
    • pixl97 #1
    • IshKebab #1
    • verdverm #1
  5. 05

    AI is reviving old engineering habits

    Several people noted that the same things teams used to wave away, type annotations, decision records, protocol specs, API wrappers, and literate explanations, now look valuable because agents benefit from them immediately. The novelty is less the artifacts than the fact that their utility is now visible and measurable in day-to-day output.

    Use the AI boom to reintroduce practices that already made systems easier to change and review. Do not frame them as “for the model” if they also improve handoffs, refactoring, and onboarding.

      Attribution:
    • seanwilson #1
    • cosmicriver #1
    • dionian #1
    • nrds #1
  6. 06

    Training people to use docs changes support load

    A support organization that trained both staff and customers to read the knowledge base cut call duration by 40 percent and total calls by 60 percent. That example sharpened the main complaint in the comments. Documentation fails less from lack of writing than from lack of habits and management support around using it.

    If support and onboarding are expensive, invest in adoption of documentation as a process change, not just a writing task. Measure deflection and cycle time so the benefit is visible to management.

      Attribution:
    • GarnetFloride #1

Against the grain

  1. 01

    Bad model behavior is not always bad docs

    Plenty of people treated agent failure as a documentation problem. Others pushed back that models can read the right thing and still choose the wrong action, invent APIs, or ignore explicit instructions. A perfect README does not fix stochastic behavior.

    Do not use model performance as your only documentation metric. Validate docs with humans and tests too, especially for workflows where the model can confidently go off-script.

      Attribution:
    • coldtea #1 #2
    • noncoml #1
  2. 02

    Good code can still beat prose for humans

    Some engineers said they would rather inspect code than read long narrative docs, and argued that “self-documenting code” was always about keeping meaning embedded close to implementation, not abolishing documentation. In that view, Claude-specific docs fill a gap for agents, while humans still benefit most from clear code, inline comments, and generated API references.

    Avoid replacing readable code with giant prose dumps. Keep the core truth in code and adjacent comments, then add higher-level docs only where structure or intent is otherwise invisible.

      Attribution:
    • wolttam #1
    • beachWholesaleS #1
    • triMichael #1
  3. 03

    Unchecked AI notes become repo poison

    A blunt minority said most agent-written summaries are incomplete, indirect, or wrong, and that stale CLAUDE.md files can be worse than no docs because they mislead future sessions and humans alike. The convenience of checking in generated notes can hide the fact that nobody is actually verifying them deeply.

    Set an expiration rule for generated docs. If nobody owns a document after the feature lands, delete it instead of letting future work inherit false context.

      Attribution:
    • dsmurrell #1
    • cyanydeez #1 #2
    • Traubenfuchs #1
  4. 04

    Documentation gains may erase the documenter

    A darker point ran underneath the productivity talk. If you become the person who translates work into agent-friendly context, you may be helping automate away the very coordination and explanation work that still justifies your role. The machine also does not reliably honor what you write, which makes the bargain even shakier.

    Keep ownership of problem framing, review, and system judgment, not just prompt prep. If your contribution is mostly turning tacit knowledge into model-ready text, assume that task will be commoditized fast.

      Attribution:
    • cadamsdotcom #1
    • noncoml #1

In plain english

API ↩
Application programming interface, a way for software to call another service programmatically.
CLAUDE.md ↩
A markdown instruction file used by Anthropic's Claude Code tooling to provide repository-specific guidance to the model.
PR ↩
Pull request, a proposed code change submitted for review before being merged into a shared codebase.
README ↩
A top-level project document that explains what a code repository is, how to use it, and other essential context.
Slack ↩
A workplace messaging and collaboration tool.
Teams ↩
Microsoft Teams, a workplace chat, calling, and meeting platform.

Reference links

Documentation and reading behavior

Examples of LLM-oriented docs

  • OpenAlex LLM Quick Reference
    Given as an example of documentation written in a style that is unusually direct and useful for both models and humans.

Productivity and culture references

AI output and reading speed references