Problem: What is documentation even for? — from "writing docs is a chore, reading them is worse" to "docs are assets for your future self, your teammates, and your AI" —— Trove problem library

Symptom

Start with a loop every developer knows: at the requirements review, the PM says "could you write some docs?", and you say yes while thinking "the code is already done, why do we need docs?".

So the docs get "written" the day before delivery — you spend three hours producing a README, an API description, and deploy steps, all the while thinking nobody will ever read this.

Three months later, you are the one reading them: the deploy steps are outdated, and one field in the API doc no longer matches the code. You fix it while cursing: writing docs is a chore, and reading them is worse.

Then there is the new kind of anxiety, courtesy of your AI colleague: you hand your project to Claude Code or Cursor to change a feature, and it produces code that "looks reasonable" but completely ignores your project conventions — it pulls in dependencies that do not exist in the project, bypasses the shared helpers you wrote, and uses a naming style that clashes with the entire codebase.

You spend more time reviewing and refactoring than you would have spent writing it yourself. You start wondering: is the AI bad, or is what I fed it bad?

Now the team-level nightmare. You join a company, and your lead says "Old Wang wrote this system, you will maintain it now". You go find Old Wang, who is busy: "just read the code, it is all in there".

You open the repo: no README, no architecture diagram, three missing env vars and two middleware dependencies, one of which was set up by Xiao Li, who left — and his handover doc is one sentence: "see my earlier email", which no longer exists.

You ask three people and get three different versions of the truth, and nobody can guarantee which is right — so you end up "verifying" everything by trial and error.

Meanwhile, Old Wang is the only person who knows everything: when he is on vacation, nobody dares touch the system.

If any of this sounds familiar — docs written and unread, AI-generated code quality like a blind box, team knowledge trapped in a few heads, newcomers unable to touch the code for months — this article is for you. It is not a template guide. It is the consensus of people educated by documentation debt, paid in overtime and rework: docs were never a deliverable for the company. They are assets for your future self, your teammates, and your AI. Whoever figures this out first skips three years of pain.

Cause

First, be clear about why docs become increasingly useless. Four misalignments — each one looks like writing, but is actually spinning in place.

First, treating "writing docs" as "checking a box". In most teams, docs are "made up" after the fact: the review needs docs, the delivery needs docs, the annual report needs docs — so docs become "deliverables".

The writer rushes to be done, the reader rushes to skip. Once docs become a formality, nobody maintains them; unmaintained docs get unread; unread docs make writing even less appealing.

That vicious cycle starts the moment docs are treated as a "task" instead of an "asset".

Second, writing docs "for the boss" instead of "for your future self". A sobering consensus: the biggest beneficiary of your docs is you, three months from now.

The deploy steps, API descriptions, and gotchas you write are mostly read by yourself — but most people write with "will this pass review?" in mind, not "can I figure this out in 30 seconds when I come back to this page three months from now?".

Wrong audience means wrong writing: either padded with boilerplate, or missing the critical details.

Third, treating "sync communication" as the only channel. Many teams pass information through meetings, word of mouth, and private chats: discussions happen in the meeting room, conclusions circulate verbally, details get lost in DMs.

A new colleague who wants to know "why is this module designed this way?" has to ask the person — who is busy, or has left, or has forgotten. Sync communication is immediate and volatile; docs are asynchronous and searchable.

Keeping knowledge only in sync channels is like keeping it on quicksand.

Fourth, treating docs and code as two separate worlds. The code changed, the docs did not; the docs were written, the code did not match. Once docs diverge from code, they lose credibility — readers who get burned stop reading docs entirely.

In the AI era, this misalignment costs more: AI cannot read your verbal knowledge — it can only read docs, code, and comments. Context that is not in your docs is context AI will "guess", and guessed code quality is a blind box.

Each experience below is a proven way to pull docs back from "formality" to "asset" — not a single opinion, but consensus repeatedly validated across independent practices.

Solution

Experience 1: Docs are the input of async collaboration — write first, then meet

Symptom: ByteDance is repeatedly studied as a collaboration benchmark, and the core of its internal communication is not meetings but Feishu docs.

Before any important discussion or meeting, the initiator must write a structured doc: background, proposal, and open questions.

The meeting starts with silent reading (the "fly-reading meeting"), then discussion focuses on the comments on the doc — no "background introduction sessions".

This looks like extra process but is actually an efficiency revolution: writing forces the author to think things through, reading puts everyone on the same information baseline, and comments and edit history make the decision process itself an artifact.

Practice: ① Doc-first — before an important discussion/design review, spend 20 minutes writing a half-page doc (background, proposal, open questions), then invite people; ② Read-then-talk — start the meeting with silent reading; talk only about differences and decisions, do not rehash background;

③ Conclusions go into the doc — write decisions into the doc on the spot instead of scattering them across meeting notes and chat logs.

Why: putting things in writing forces you to turn "feelings" into "judgments" and "approximately" into "specifically". Verbal communication is high-bandwidth but volatile; docs are low-bandwidth but durable.

The value of async collaboration is not replacing communication — it is making communication reviewable, replayable, and reusable.

Experience 2: In the AI era, docs are "super prompts" for AI — Garbage In, Garbage Out

Symptom: many people complain AI-generated code is unstable: one task produces elegant code, the next produces something with a latent security hole.

Look closer and the root cause is usually not model capability but GIGO — an AI coding assistant is like a brilliant senior engineer with zero knowledge of your project: the vaguer and more context-free your input, the further the output drifts.

Traditional docs are "written for humans" (PRD, architecture docs, DB design); in the AI era they are redefined as structured context for AI coding tools.

Feed it a full doc set (requirements + architecture + data model + frontend conventions) and output quality changes qualitatively; feed it "build an e-commerce app" and it guesses.

Practice: ① Write a project skeleton doc — README covering "what this project is, tech stack, directory layout, how to run, conventions" — this is context for humans and initial context for AI; ② Document the "why" of key decisions — write "why this design" in site docs so AI understands constraints instead of guessing;

③ Feed context before asking AI to code — make sure it can see the README, API docs, and existing code style; ④ Close the loop — use AI to draft docs (PRD/API site docs review them, then use the docs to drive AI coding.

Why: the upper bound of AI output quality is set by the lower bound of the context you feed it.

Once docs shift from "guides for humans" to "super prompts for AI", writing docs stops being an extra burden and becomes the prerequisite investment that makes AI work for you — the math works out in your favor.

Experience 3: Knowledge silos and single points of failure are broken by documented knowledge — tribal knowledge must become documented knowledge

Symptom: many teams live with "knowledge in the heads of people": only Old Wang can maintain a system, only Xiao Li knows a config, newcomers have to ask around one by one. That is classic "tribal knowledge" — undocumented knowledge living in individuals.

Its costs: single points of failure (the whole team stalls when Old Wang is on vacation), information silos (each department does its own thing), information drift (three people, three versions).

A subtler symptom is the "haunted graveyard": code nobody dares touch because the person who understood it is gone, guarded by comments like "never delete, it will break".

Practice: ① Critical knowledge must land in docs — deployment, env vars, design decisions, gotchas — anything "only one person knows" becomes a doc; ② Docs and tribal knowledge complement each other — docs are the skeleton, experts are the flesh: docs answer "what/how", experts answer "why/edge cases";

③ Build a canonical "single source of truth" — developer guide, coding practice standards, FAQ manual, maintained and reviewed by subject-matter experts, so the team checks docs before asking people;

④ Sink new knowledge promptly — you solved a problem nobody else has hit?

Write it down instead of keeping it only in your head.

Why: software engineering is fundamentally about people, but knowledge cannot live only in people. Documented knowledge is what inherits and flows across a team or an entire organization — it is the only carrier that does not leave when people do.

The goal is not to eliminate experts; it is to make sure what experts know is no longer known only by experts.

Experience 4: Writing docs is engineering discipline, not wasted time — in a proper development process, 30% of time on docs is normal

Symptom: a widely circulated essay "to our restless software industry peers" tells a real story: the author team took an outsourcing project in India.

The other side delivered a 40-page SRS during requirements analysis — multi-author but consistent in style and rich in detail; every phase had a review; the QA attended meetings with a checklist and ticked items off.

The other side scheduled by "300 lines per person-month" — the author thought "we do six or seven hundred", and the reply was "this plan is built on quality assurance".

The reflection of the author: what we lacked was not coding skill, it was engineering discipline. One line from that essay gets quoted constantly: "30% of the working time of a coder spent writing technical docs is normal; for senior engineers and system analysts the ratio is even higher. Without docs, a software system lacks vitality — debugging, upgrading, and module reuse will all hit serious trouble."

Practice: ① Count doc time as working time — requirements, design, coding, testing, docs: docs are a phase of development, not an appendix to coding; ② Write before you code — for important modules, write a short design doc first (goal/proposal/interfaces/risks) and then code — rework drops noticeably;

③ Review docs like code — consistent style, accurate content, complete coverage; ④ Do not pit "writing docs" against "writing code" — docs are not time stolen from coding; they are the investment that keeps coding from being redone.

Why: doc quality directly determines the vitality of a system — debugging, upgrading, and reuse all lean on it.

Treat docs as "something outside coding" and they become "something patched after coding"; treat them as engineering discipline and they become "the thing that keeps code from rework".

The lesson of the India project is not that process is tedious — it is that good docs kill 80% of problems during requirements analysis.

Experience 5: Keep docs alive — updates are discipline, flow is a mechanism, readability is the floor

Symptom: the leading cause of doc death is not being unwritten, it is being unupdated. Code changed, docs did not; readers burned once stop trusting docs forever.

Equally common: docs exist but nobody knows where they are or which one to read — the "knowledge graveyard".

And one layer deeper: the writer has full context, the reader has none, so "written" docs can still be unreadable.

Practice: ① Fix errors on sight — see a mistake or gap in a doc, update it immediately; do not wait for a cleanup sprint; ② Document every new process/step — you created a new dev step, record it in a doc and make it easy to find; ③ Build a feedback channel — readers can report "this is wrong", maintainers can respond;

④ Use code review as a "readability process" — code review spreads best practices as written comments, combining the strengths of documented knowledge and expert knowledge;

⑤ Promote docs instead of re-explaining — when someone asks, point them to the doc first, then add live explanation where needed — knowledge gets sunk instead of flowing back into individual heads.

Why: the enemies of docs are "stale" and "undiscoverable". Update discipline handles stale; flow mechanisms handle undiscoverable; readability handles "written but useless".

Get all three right and docs become a living asset — they answer questions for you, save your team time, and provide context for your AI.

How to start (L1 execution checklist)

1. This week, write a one-page "bootstrap doc" for your current project: what it is, tech stack, how to run it, directory layout, how to deploy — written for yourself, under 30 minutes;
2. For the next design meeting, write a half-page "background + proposal + open questions" before inviting people, and read the doc first at the meeting;
3. From today, feed context before asking AI to touch code: README, key interfaces, code style conventions — then compare the output quality;
4. The first problem you solve that nobody else has hit: write a note/doc into the project instead of keeping it in your head;
5. When you spot an error in a doc, fix it on the spot. Do not accumulate.

How to adapt to your context (L3 deep layer)

• Personal projects: make "for my future self" the first principle — README says how to run, why this design, what you hit; your future self will thank you; feed the README and key file paths to AI before asking it to change code — output quality will visibly improve.
• Small teams (5-15 people): start with three things — doc-first (half a page before discussions), a single source of truth (deploy/env vars/gotchas in one fixed place), and fix errors on sight; spend 10 minutes a week maintaining docs so they do not rot.
• Large teams: docs need to be "treated as a product" — canonical sources of information + subject-matter expert review + feedback loops + searchability; code review carries the "readability process" role; "read-the-doc-then-discuss" meetings eliminate most ineffective meetings.
• AI era: docs shift from "for humans" to "human-machine shared" — AI reads docs, generates code, drafts docs; humans review and maintain; "context management" is the new core skill of the AI-coding era, and docs are where context management starts; when AI-generated code quality drops, check whether the context you fed it was sufficient before blaming the AI.
• If you are stuck at "docs unread / knowledge requires asking people / AI output is a blind box": start with the smallest loop — write a bootstrap doc for the current project; feed the README to AI next time; write a note every time you solve a new problem. Three weeks later you will see the difference: the most obvious one is that you no longer have to "excavate" your own project from three months ago.

(Final words) The most counter-intuitive thing about documentation: it does not save the you of today, it saves the you of three months from now. My own scar: a project only I understood, until I came back from leave and could not understand my own code.

Then I started treating the README as a letter to my future self — how to run it, why it is designed this way, what traps I hit — and everything changed.

Do not make "documentation" sound grand. Just write one thing: what will the you of some future moment need to know?