This skill does two things. First, get from the maintainer the material only they have: the facts, who the readers are, and where they stand on the trade-offs. Then write this material into documentation that is easy for readers to read. The second step does the same thing as translation: not a single word of meaning is changed, only the phrasing is swapped for something a reader can understand by reading straight through. To do the second step well, you first need to know how readers read, and why models default to writing in a way that is hard for readers to read.
How readers read
A reader can only hold a few things at a time. With every sentence they read, they have to attach that sentence to something they are already holding; if it attaches, the sentence becomes theirs, if it doesn't, they either leave it hanging or fill in the missing step themselves. So a sentence should start from something the reader already has and add only one new thing. In documentation where every sentence is a brand-new fact, the reader has nothing to anchor to and loses a few sentences after reading a few.
Readers have to judge what matters as they read. In prose there are only a few signals that can convey this judgment: length (how many words the author spent), repetition (saying the same thing again through consequences, examples, numbers), position (the first sentence of a paragraph), an explicitly stated stance (“not recommended,” “the most common mistake is”). Documentation where every paragraph is about the same length and every sentence stops at the same level of abstraction erases these signals, and the reader can only judge sentence by sentence which one matters.
Recognizing is cheap; generating is expensive. When readers reach an example, they recognize that it is talking about the previous sentence, use it or skip it, and it costs almost no effort; when they reach a sentence that omits the subject, an abbreviation coined on the spot, or a conclusion that skips intermediate steps, they have to generate the omitted part themselves. Human maintainers' documentation is actually very short after deleting “redundancy,” but restatement can make an abstract statement concrete, and it can also recall earlier text, deepen the impression, and let the reader sense what matters. Readers don't have to receive a new fact in every sentence; appropriately restating existing content can keep them reading on. When documentation is very short and dense, these connections may instead need the reader to rebuild them.
What the reader already knows determines what counts as “something they already have.” A design doc written for the same team and a README written for external users, with the same facts, need different things spelled out. So when gathering material, ask clearly who the readers are; this is not a formality.
Why models default to writing that way
Models don't have these constraints. They hold the complete context and don't feel the cost of every sentence being new, so they write by coverage: one fact per sentence, uniform density, no sense of what matters.
They lack the material only maintainers have. Without facts they fill in templates (“cross-platform support,” “production-proven”); without a stance they lay out options in a symmetrical flat list; without specific readers they write “whether you're a beginner or an expert.”
They are under pressure from the output budget. When the system prompt asks for conciseness, they drop function words, use arrows and colon labels instead of sentences, write rules as aphorisms, and write paragraphs as outlines. This shows up first where the writer themselves feels it “should be short anyway”: rules, headings, list items.
It has its own register conventions. Favored words (empower, it's worth noting, robust, seamless), sentence patterns ("not X but Y", triples, sentence-final -ing tails), punctuation (em dashes, signposting colons, bold everywhere), skeletons (introduction-body-conclusion, a bold subheading for every paragraph, a summary at the end of each paragraph), plus carrying one language's grammatical habits into another. Once readers recognize this as model-written, their trust in the content drops with it.
Of these four, the first two determine whether the document has substance and whether readers can get through it; the last two determine whether readers can tell it was written by a model. All four need handling, in the order of the first two first. Just swapping words without adding material leaves the skeleton in place; just adding material without changing the expression and readers are pulled out of it in the first paragraph.
When to use
- Writing or rewriting a README, Getting started, usage guide, module description, design doc, or proposal, in Chinese or English.
- The user says the document is "unnatural", "sounds AI-written", "too empty", or "too dense" and asks for a fix.
- Organizing a description for others from code, issues, conversation logs, or a list the user provided.
- Translating a document. Translation does only the second step: the target language follows local conventions, terms and identifiers are not over-translated; structure, facts, and stance follow the original, without applying rewriting authority.
Blogs and personal essays have a different tone and set of trade-offs and are not handled here; marketing pages and release announcements aim to persuade and are also out. Generating API references from source is left to tools. Merely fixing grammar and typos doesn't require reading this skill.
First get the material only the maintainer has
Facts
Every statement can point to a source: code, command output, an issue, a measurement, or a list the user provided. Numbers, promises, roadmaps, and performance adjectives without a source are not written. When facts are missing, ask the user or state what evidence is lacking; write that something is untested or undecided only when a source confirms it, and don't make things up to fill a section. Human documentation is normally missing parts, and absence is a normal state: if there's no CONTRIBUTING, don't write a contribution guide.
Conclusions drawn from the given facts take only one step, and readers can verify them themselves using the facts already in the text. For example, given that "each worker is rate-limited to 50 requests/sec individually" and "there are 6 workers in total", writing "the total is 300 requests/sec" is fine; writing "this will raise P99 latency" is not, because nothing in the text supports it. General domain knowledge ("TOML strings must be quoted") can be used to explain why, but write it as a concrete statement readers can check, and don't use it to stand in for a measurement the project hasn't done itself.
Readers
Be specific about "what the people coming to this page already know, what they're here to do, and what decision they need to make after reading". README readers are deciding whether to use it and how to run it the first time; design doc readers are colleagues who will review it and may object; guide readers have a specific task in hand. Before writing, state in one sentence who the reader is; if unsure, ask.
Facts being true doesn't mean they should be written. When the maintainer says "readers don't need to know what it uses underneath, we don't want them depending on it", write "the underlying implementation is not part of the contract and may change", without naming it.
Stance
Maintainers will write "not recommended", "not supported", "this threshold has no data behind it, we're setting it this way for now", "if ..., don't use this". Documentation should make the trade-off for the reader, telling them which path is the default, which is the exception, and when not to use the thing; don't lay all the options out as a symmetrical list for readers to choose from themselves.
Then write the material into documentation that saves the reader effort
Calibrate your voice with similar documents
Rules and reminders alone may not be enough; when writing, you may still fall back on old habits. When writing documentation, the nearest text in context is usually the task description and what the model itself just wrote, so it is easy to carry over the same tone. This skill's description of human documents cannot replace the text itself. Before starting, read one or two maintainer documents of the same kind and same language in full, from beginning to end, and notice how problems are explained and how explanations connect to consequences. Documents already written by someone in the project itself are best, since readers are already used to their tone; if there are none, pick samples of the same type from human-samples.md and read them. The purpose of reading is to bring that way of speaking into the writing that follows, not to imitate its sentences, nor to carry over that project's facts or formatting conventions. Text already read and suitable for the current task can continue to be used. When offline or when links fail, calibrate with the project documentation that is available; if the authorship is unknown, do not call it a human sample. If no suitable sample exists, you can still write based on the task materials, and state the limitation clearly in the delivery notes; do not let the search for samples block a task for which the existing materials are sufficient.
Who you are when writing
When writing, you are the maintainer of this project, the one who has always written its documentation, and sitting in front of you is a specific reader who has just encountered the question this page is meant to answer. You make trade-offs for them, start with something they can follow, and answer in the next sentence what they would ask next. This identity lends only its way of speaking, not its memory: facts still come only from the materials, what is not in the materials you do not know, and you do not fill it in just because "a maintainer should know it." It is also not writing a blog. In experiments, when writers were also given a blogger identity, the output became more readable but also brought in blog things: cute section headings, aphoristic endings, a bullet-point summary at the end, details filled in from a persona's character. In documentation these are a different tone.
Decide what matters before writing
Before starting, think clearly about what decision the reader needs to make after reading, and which information is indispensable for making that decision or completing the operation. Places that are easy to misunderstand and have larger consequences deserve elaboration, connecting the mechanism to consequences and examples; independent parameters and simple facts can be written briefly. Length is determined by what the explanation needs, not stretched or cut to make sections differ in length. Translation and targeted revision follow the scope of the original text and do not change the original meaning by redistributing emphasis.
TiDB used six sentences to explain Raft: writes must go to a majority of replicas; so losing a minority of replicas still leaves the latest data; for example, with 3 replicas, writing to 2 counts as success; compared with primary-secondary synchronous replication, latency depends on the fastest two; so geo-distributed active-active becomes possible; in a two-region three-center scenario, only the local center and the nearest center need to write successfully. In the same article, deployment got only two sentences. Readers know without reading the content that the author considers Raft important.
Start each sentence from what the reader already has
First answer the question the reader has right now, then add the one step they still lack in order to understand or act. If a mechanism leaves people unsure what to do, state the consequence; if the text is still abstract, explain it with a scenario or example from the materials. When the reader can already act on it, this paragraph can end; there is no need to go through the order of "mechanism, consequence, example" again. Several closely related facts can be stated in succession; there is no need to insert an explanation after every sentence. Examples and numbers may come only from the existing materials.
When every sentence in a section introduces a brand-new fact and the pieces don't connect, there is a way: imagine it as a question a colleague has just asked in a chat, the question this section is meant to answer. Write it first the way you would reply to them: answer what they most want to know first, then continue in the order they would follow up. When you're done, strip away the reply shell—remove the forms of address, the opening, and phrases like "you asked" or "simply put"—and keep the content and order. A reply naturally satisfies the two points above: the question is something the reader already has, and answering what was asked first is the prioritization. The cost is that a reply only answers what was asked, so after writing, check against the material for anything that should be covered but isn't.
Whether to delete a sentence depends on what it does for the reader here. Even if a restatement adds no new facts, it may recall earlier text, emphasize importance, deepen impression, or remind of the next action; repetition at the same level of abstraction, summaries, and transitions can also serve these purposes. Don't delete just because "it was said earlier" or because "the facts are still complete after deletion." Delete or revise only when you specifically judge that it doesn't help in the current context and instead interrupts reading or dilutes the focus; when unsure, don't compress for the sake of information density.
The structure of a document is determined by what content it has
The first sentence of a README states what it is, who it's for, and what problem it solves, using declarative sentences. Then comes the information readers need to make decisions and get started: installation, a minimal runnable example, counterintuitive key behaviors, limitations and known issues, and when not to use it. Don't leave empty headings for things that don't exist.
In the background of a design document, put the real problem or incident; the proposal should state clearly what was decided; write a separate section on the options considered but not adopted and why; spell out costs, known issues, and numbers without data support; list undecided items; and write concrete actions for implementation and verification. Section headings can directly be assertions.
Organize the guide in the order of the reader's tasks, giving copyable commands and expected results at each step.
Use lists to enumerate things that are inherently parallel, such as supported platforms and command-line arguments; write explanations, trade-offs, and causation in paragraphs. Write as many items as there are, without adding one to make three or deleting one for symmetry. Put facts in the items—versions, numbers, names, behaviors—rather than adjectives.
When writing sentences
- Replace degree words and vague hedging with numbers, conditions, and concrete behavior. Hedging should state which parameter it is, what its current value is, why it's uncertain, and what will decide it later. Replace "specific parameters may need to be adjusted according to actual conditions" with "the request timeout defaults to 30 seconds. This value hasn't been tested; it was set based on experience from previous projects. After launch, if there are many timeout alerts, consider increasing it."
- Examples and quotations should be understandable to readers without background. A sentence holds up in its original document because the preceding text defined the terms or the readers are the same team; when moved into another document, that support is gone.
- Make the relationships in a sentence readable. Mechanisms and exceptions, causes and conclusions can be said together; split the sentence when there are too many modifiers or the references are unclear. Sentence length is determined by the content and the target language, not padded or truncated to match a sample average.
- Write the main text as sentences readers can follow, without omitting necessary subjects, conditions, and connections. Fragments in headings, parameter tables, and lists can be kept if they can be understood independently. When brevity is required, first delete filler that doesn't help reading and secondary elaboration, and keep useful restatements, operational prerequisites, limitations, evidence, and content the user requested; when it truly doesn't fit, state the scope or expand in layers rather than silently writing less.
- Colloquialism should follow the project's existing documentation; if there's no sample, lean neutral. Don't deliberately get colloquial or leave in errors just to seem human.
- Use one name for the same thing throughout. Prefer accurate terms familiar to the project and the reader community; don't invent your own abbreviations, and don't uniformly break mature terms into lengthy explanations. For example, for service maintainers, "configuration hot update" is clearer than the vague "hot loading"; the reader already understands this concept, so just use it, and add operational consequences like "must restart after modification" when needed. Whether a term needs explaining depends on the reader, not on whether it's short or abstract.
- Bold only warnings the reader must see when skimming. Headings should be noun phrases, or questions the reader would actually ask.
- State the conclusion directly and positively. Use "not X, but Y" only when X is genuinely a misunderstanding the reader would have. When a dash expresses an unclear relationship, adjust the punctuation or sentence; if "the core is:" or "the key is:" only serves as filler, just say what follows directly.
- Write Chinese with Chinese word order and function words, and English with English articles, tense, and clauses. When translating, terms, commands, and community idioms should follow the project's and readers' usage; don't coin translations just to be "all Chinese" or "all English." For symptoms in both directions and the list of over-translation, see language-notes.md。
Review and proofreading
After the first draft is complete, read it through again as a reader, and verify facts, scope, promises, and uncertainties against the sources. Check the premises in the order the reader actually operates: for example, restore overwrites data, so the backup reminder should come before the restore command. Change only when you find a concrete problem; if the expression is already appropriate, keep the original draft—don't swap words or delete repetition just to look reviewed. Proofreading is usually done by the writer; it doesn't require an independent Agent, a fixed number of rounds, or an extra proofreading report. Use the following perspectives as needed.
Check whether the reader can get from mechanism to consequence, and from explanation to operation. Do hard-to-understand places have concrete scenarios or examples? Code, numbers, and directly described scenarios also count as examples; the word "for example" need not appear. Section length, sentence length, and the frequency of example words can only hint at where to reread—they can't by themselves determine that rewriting is needed; short pieces, reference pages, and parallel parameter descriptions also don't need deliberately varied levels.
When tone needs calibration, read the draft side by side with the corresponding explanatory paragraphs of similar documents you've read; for samples and observed features, see human-samples.md. Ask paragraph by paragraph: what will the reader ask here, and is it answered? Which words are adjectives rather than facts? Which sentence was filled in from a template?
If there are still unnatural expressions, check the corresponding symptoms from the content level down to the vocabulary level per ai-patterns.md . For each hit, go back to the material and ask what it's standing in for—add facts or delete it; merely swapping synonyms doesn't count as fixed. The "can't be used as criteria" table in the same file is a hard constraint: question-form headings, "X is a..." openings, "first... second..." in the body, nominalized long sentences, examples, and repetition are equally common in human documents—don't change them to "seem more human."
Revising existing documentation
Change only form, not facts, promises, or uncertainties. Handle three categories separately:
- Form issues. Delete adjectives, slogans, template sentences, transitions, and closings ("ultimate performance," "let us," "Happy coding") or replace them with facts already in the text; expression-layer traces per ai-patterns.md Revise item by item; expand hard-to-understand telegraphic style into sentences; rearrange translationese according to the target language; when readers lack a basis for understanding or action, add the relevant consequences or examples, with content drawn only from existing facts, and do not expand merely to make paragraph density uniform. Before starting, first lock down commands, parameter names, values, URLs, and quoted source text.
- Unsourced claims. Performance comparisons, "verified in extensive production environments," roadmaps, support lists: verify what can be checked in code or the repository; for what cannot be verified, preserve the original meaning and original degree of certainty, list it outside the main text as an item requiring maintainer confirmation, and do not arbitrarily strengthen, weaken, or replace it with another unverified claim. When writing new documentation, do not present claims lacking evidence as facts.
- Point out suspected factual errors separately; do not draw conclusions on the author's behalf.
Preserve the original frontmatter, links, code, commands, and technical identifiers; the project's existing formatting conventions (emoji feature lists, numbered subsections) are not the object to be fixed this time unless the user requests it.
Delivery
Deliver the manuscript itself; do not leave explanations in the main text about the writing process or "AI flavor removed" or the like. Preserve source links, quotations, and version information that support claims. Handle links according to the document's target publication location; temporary preview files do not change the target location and do not require changing repository-relative links to local absolute paths. Adjust links according to the new location only when actually migrating the document. Also attach a short note: which common content was omitted or written as pending due to lack of facts, which inferences were steps you took yourself, which tradeoffs were made on the reader's behalf, and which places require maintainers to supplement.