Doc Writing

doc-writing

How to write a document this user accepts, organized by document type, with a linter for the rules a machine can check.

Master TOC

• How to use this
• The two rules that caused the most friction
• Universal core
• Per document type
• When the requirement depends on context
• Lint before you ship
• Keeping this skill true

How to use this

Read the universal core once. Then read the one section for the type you are writing, and use its skeleton as the outline. Write the document. Run scripts/doccheck.py on it before you call it done.

Marker legend. Two markers appear throughout, and both mean something specific.

1. B12 points at consolidated rule 12 in the mined preference set. The linter quotes these ids back in its findings so a rule can be traced to its evidence.
2. #3 is the position in the frequency ranking, meaning how many separate turns the user spent repeating the point. A high rank is not a matter of taste, it is a record of repeated correction.

The source is two real project sessions from July 2026, 262 prompts total, mined into 102 verbatim preferences and 48 consolidated rules.

The two rules that caused the most friction

1. Define every term you introduce, in place (B6, rank #1)

Across roughly eight separate turns the user had to stop the work and ask what a word meant. Every one of those words was the agent's own wording, so this friction was self inflicted. The questions looked like this.

特别解释一下langchain 4-tool sql是什么东西 · 请解释一下es是什么 · 项目级联是啥？什么入口合并？ · 报告状态静默不达，这个是啥意思？

The rule covers acronyms, product names, internal jargon, and any phrase you coined while writing. Gloss it at first use, inside the sentence, in one of these forms.

A glossary section at the top does not excuse an unglossed term further down. If you invented the phrase while writing the sentence, that is exactly the case that needs the gloss.

2. A manual (手册) AND an in-app guide (引导) per feature, and a guide is a use case flow (B13, B14, rank #2)

Roughly ten turns, including an outright rejection the user asked be recorded permanently.

Agent的那个引导有点儿奇怪，他就是简单的罗列了一下几个按钮，根本没有整个的流程，所有的引导它是按照功能流程来的，也就是user case来的，即使是同一大模块儿的功能，如果它有好几种使用方式/cases，那实际上应该有好几种，好几个引导才对，而不能单纯的就是把功能罗列一下，请对这个进行一个整体的优化，并且记下这个要求。

What this settles.

1. Every shipped feature gets both artifacts. A written manual, and an interactive guide inside the product. Either may be standalone or folded into the feature surface.
2. A guide is an end to end flow through a real task, never an enumeration of the buttons on screen. Listing controls was rejected by name.
3. One module with N distinct ways of being used gets N guides, one per use case.
4. Manuals and guides land feature by feature as each feature finishes, not batched at the end of the project.
5. Coverage is recursive. The manual and guide system itself, and the bug report module, each need their own manual and guide. There is no meta exemption.

The interactive guide has a fixed navigation contract, listed in manual.

Universal core

These apply to every document. The first ten are ranked by how often the user had to repeat them, and the last column names the doccheck.py check that enforces the rule mechanically.

Also always true, grouped by what they govern.

Honesty of content.

1. Nothing is guessed (B2). When something cannot be verified, the document says so instead of asserting it.
2. Cite the source of every fact, and for any number, precise value, or list, include the code and the generation procedure that produced it (B3).
3. Label every mock or demo item visibly so nobody reads it as real (B37).
4. Say when a behaviour is deliberate rather than an oversight, and record the reasoning (B19). The reader has to be able to tell an omission from a decision.
5. Being a prototype never licenses narrowing the analysis (B29).

Writing.

1. Natural human prose with the AI flavour removed (B7). Chinese reads as Chinese, never as a term by term translation of English jargon.
2. One document serves two audiences (B7). Deep enough technically for an engineer, while the top level narrative and the diagrams stay legible to a data analyst.
3. Structured, repetitive, or multi field information goes in a table (B8). Per entity outcomes get a classification table plus statistics.
4. Schemas, attributes, and storage formats always carry a worked example (B20).
5. Names state plainly what the thing is for (B47), documents included.

Placement and delivery.

1. Survey and cite every existing document on the topic before writing, and fix what you find stale on the way (B10, B43).
2. One topic, one main document (B9). New work merges into it. Scattered related documents get consolidated in, not left as parallel copies.
3. Documentation centralizes in the dedicated docs repo, laid out as one subdirectory for platform wide material plus one per code repo (B30).
4. Migrating a document means adding a link in the source repo and keeping the original, with one exception covered in the decision rules (B31).
5. A document counts as delivered once it is pushed and findable (B39). Verify it renders where it will be read, since a section that fails to render is a defect the user reports (B12).
6. Write every newly discovered requirement and every working configuration straight into the relevant document, making the working configuration its default example (B35).

Per document type

spec — design and architecture

The section skeleton, derived from the document the user promoted to the house template.

1. Purpose and scope
2. Terminology, glossing every term the document uses
3. Problem history — what went wrong before, what the old design was, why it failed
4. Architecture — mermaid architecture diagram, data flow diagram, storage and cache diagram
5. Code and data map — every module, table, and attribute with a full link, each placed at its correct position in the diagrams
6. Storage format, with a worked example
7. Operating it — what CI/CD automates, what a human does, and whether the whole flow runs without an AI agent
8. Per entity outcomes — classification table, statistics, accuracy per method, what needs human checking
9. Special cases and deliberate decisions, each flagged rather than folded silently into the general case
10. How comparable tools solve the same problem
11. Verification — how each claim was proven, and how a tester or frontend engineer re-proves it
12. Remaining tasks and future work, highlighted, each deferred item carrying its risk and how to avoid it

Extra rules for this type.

1. Research established practice before designing a format or scheme, compare the alternatives in writing, and give an explicit recommendation (B28).
2. Split every operational procedure into what CI/CD can automate and what a human must do, listing the manual set exhaustively (B16).
3. Keep the manual how to alongside any automation plan, even after the automation is scheduled (B17).
4. Environment scoped documents stay strictly in scope (B36). A production instruction never appears in the staging document.
5. When a diagnostic procedure works, the executed procedure becomes a document, and that document becomes the first reference for that class of failure (B41).
6. A written artifact that is also machine input follows an established open source format, lives in a designated location, carries a description per entry stating what it verifies, and is executable through one code path (B44).

doccheck --type spec requires a mermaid diagram, a verification section, and a remaining-tasks section.

manual — 手册 and 引导

The manual skeleton.

1. What this feature is and what it is for
2. Prerequisites
3. Steps, starting from absolute zero (B15). Open the vendor site, create the account, log in. Assume no prior state
4. Screenshots of the surfaces being described (B38)
5. The problems hit along the way and how to get past them. The failure history is part of the deliverable, not an appendix
6. How to check it worked, written for the person doing the checking
7. Where to report a bug

The in-app guide contract, all five points from the rejection that produced it.

1. Each guide is one use case flow. A module with several usage cases gets several guides.
2. The guide starts at step 1, never at step 2 or 3.
3. It offers a previous step control and a quit control at every step.
4. On exit it returns the reader to the matching manual page.
5. It records completion per user, and still lets that user run it again.

Extra rules for this type.

1. Anything the user has to perform is broken into explicit numbered steps, not summarized (B15).
2. Issues raised by named colleagues are recorded with attribution, executed, and then absorbed into the manual and the guide. They are closed only once absorbed (B42).
3. When another team owns the other side of an integration, ship API documentation plus a manual plus a guide aimed at that team (B42).
4. Coverage is recursive. The manual system and the bug report module get their own manual and guide (B13).

doccheck --type manual requires a mermaid diagram and a verification section.

report — audit, bug fix, test results

Field lists by report subtype. These are the fields the user named, so a report missing one gets sent back.

Extra rules for this type.

1. Report the finished subset as it lands rather than holding everything until the batch completes (B24). The user verifies in parallel.
2. Root cause before fix. State whether the fault was a regression or pre-existing fragility, and why it started firing now.
3. Everything needing the user's hand, authorization, or decision goes in one block at the end, after checking whether it could be automated instead (B25).
4. Alongside an exhaustive report, produce the short paste into chat summary (B46).

doccheck --type report requires a verification section and a remaining-tasks section.

readme

The README opens with per audience entry points, and that table is the first thing a newcomer sees (B33).

1. One row per role. Frontend, backend, database, and agent developers, QA, end users, marketing, the CEO, and the UI designer.
2. Each role qualified by which platform it belongs to, since the organization runs more than one.
3. Each row lists what to read, marked as must read or read later.
4. If several versions of this table already exist, consolidate them and move the result somewhere more visible.

Extra rules for this type.

1. Process rules everyone must follow go somewhere impossible to miss, backed by a hard enforcement mechanism such as branch protection or a pre-push hook where one exists (B34). Analyse the flow for defects before writing it down.
2. Setup instructions start from absolute zero (B15).
3. A new repository ships with a sensible file structure, a written explanation of it, a documentation system, and a matching update to the central docs repo (B32).

release-notes

1. What shipped, one entry per item, each stating what it is and how to test it from the user's perspective, each with its link (B22, B24).
2. Bug fixes with their IDs and verification links (B21).
3. The short broadcast summary to paste into chat, pointing at the full document (B46).

plan

The user's standing sequence is list everything, then change one at a time, then review one at a time from several angles (B27).

1. Inventory first. The complete list of pages, components, or items to touch, written before anything is touched, so nothing is skipped (B26).
2. Research on established practice, a comparison of the alternatives, and an explicit recommendation (B28).
3. Phases, each with its deliverables.
4. The automation split, and whether the flow runs without an AI agent (B16).
5. Risks, each with how to avoid it (B17).
6. Remaining and future tasks, highlighted (B18).
7. A mermaid diagram of the flow being planned (B5).

doccheck --type plan requires a mermaid diagram and a remaining-tasks section.

handoff

Written when context or budget runs low, and also before any compaction (B40).

1. Filename HANDOFF-YYYY-MM-DD.md, under docs/platform/, on branch handoff/session-YYYY-MM-DD.
2. Pushed to the remote, and the reply carries its URL. The next session resumes from that URL.
3. Contents: where things stand · what is done and verified, with links · what is in flight · the exact next step · blockers and the decisions still owed by the user · every link needed to resume without re-deriving anything.

When the requirement depends on context

Six places where the requirements look contradictory across turns but are not. Each is a decision rule.

Lint before you ship

python3 skills/doc-writing/scripts/doccheck.py <file.md> [--type spec|manual|report|readme|release-notes|plan|handoff]
                                               [--json] [--strict]

Eight checks, each citing the mined rule it enforces. Exit codes are 0 clean, 1 warnings present, 2 errors present. With --strict, info level findings fail too. A secret is always an error and always exits 2, and the matched text is never echoed, because printing it would put the secret back into the session.

Per type required sections, the acronym stoplist, staleness markers, and filename to type inference live in doccheck.config.json, editable without touching the script. Secret patterns stay in the script on purpose, so a document cannot weaken its own leak check.

The linter covers what a machine can see. It cannot tell you whether a claim was actually verified, whether a guide is a use case flow or a button list, or whether the inventory was enumerated first. Those stay with you.

Tests live in scripts/test_doccheck.py, 20 cases with a negative case per check, run with python3 scripts/test_doccheck.py.

Keeping this skill true

These rules came from real document work, and real document work is what corrects them. When writing a document reveals that a rule here is wrong, missing, or too broad, file it.

node ~/.claude/agent-harness/bin/harness-feedback.mjs --feature skills/doc-writing \
  --verdict needs-update --why "..." --proposal "..."

Use --verdict needs-update when a rule is right in principle but stale in detail, and --verdict missing-capability when the document work revealed something this skill should cover and does not. /harness-sync drains the queue into real edits.

Filing takes one command and never blocks the document in progress. Write the document first, file second. This is the mechanism behind B48, which says a documentation practice that proves out gets written into the harness so it applies by default rather than living in one conversation.