better-readme

Better README

A README is the consumer's first — and maybe only — look at the project. It is also the project's contract: the documentation, not the code, defines what the project does and what it promises to keep stable. No README means no abstraction — readers must read the source to learn the interface, and the interface/implementation boundary disappears. The job is not to sell; it is to let each reader evaluate fit as fast as possible, including bailing out early. Structure every README as a cognitive funnel: broadest, most decision-relevant facts first, deeper detail only for readers who already decided to stay.

The reference framework is noffle's Art of README. An archived copy lives in this skill at references/art-of-readme.md — the upstream repository link has gone offline, so consult the local copy when you need the original checklist or the reasoning behind a rule. Do not reproduce it in the READMEs you write — apply it.

The funnel

Name → one-liner → (background if the domain is unfamiliar) → usage, runnable → install → API (or a link to it) → caveats → contributing → license.

• Each layer should let a reader short-circuit: "not for me" in 30 seconds is

a success, not a failure.

• Install/API order depends on what the thing is. For libraries whose value

is the API, readers vet the API before they bother installing: usage → API → install (the article's original order). For apps, CLIs, and out-of-the-box tools that expose no external API, install/setup comes right after usage, and the API section may not exist at all.

• Non-permissive license (AGPL/SSPL/…): badge or note at the top, full text

at the bottom. License incompatibility is the fastest disqualifier; do not bury it.

• Images that carry critical information must live in the repo, not on an

external host — the README outlives the host.

Audit before rewriting

Read the current README top to bottom and score it against the funnel. Failure modes seen in real audits:

• Audience mixing. Maintainer content (release runbooks, CI secrets tables,

repo-structure trees, debug guides) interleaved with consumer content. This is the most common and most damaging pattern.

• Funnel collapse. Adapter/internals detail in the first 50 lines, before

the reader knows whether the tool is for them.

• Duplication. The same fact (Node version, incremental rebuilds, runtime

details) stated two or three times. Keep one statement, at the shallowest layer where a consumer needs it.

• One-tool-centric framing. A table or section written when the project

supported one tool, still leading with that tool's specifics after it supports ten. Verify the truth against the code — the old text may be not just biased but wrong (missing entries, superseded semantics).

• Staleness. Dead relative links, version ranges that drifted ("ADRs

0001–0006" when 0015 exists), references to deleted files.

• Unlinked API docs. Detailed reference exists in the repo but the README

never links it.

Pre-flight checks (do these before editing anything)

1. `git status` first. Never overwrite files in a dirty worktree — the

README may carry the owner's uncommitted work. If the tree is dirty, work in a fresh worktree off origin/main; that also keeps the PR free of unrelated changes.

1. Diff the branch against `origin/main`. READMEs drift between branches.

Base the rewrite on what main actually says today, not on the checkout.

1. Grep tests and CI for `README`/`CONTRIBUTING` strings. Projects pin doc

content in tests: exact headings, file lists, required phrases. Know what is pinned before restructuring — otherwise CI fails after the rewrite.

1. Check for derived documents. Packaging READMEs, website copies, or

generated docs that duplicate the README may need the same treatment or a deliberate out-of-scope note.

Rewriting rules

• Consumer content only, in funnel order. Maintainer procedures move to

CONTRIBUTING.md or docs/ — moved, not deleted — with a pointer link left behind.

• One home per fact. If a detail now lives in a reference doc, link it; do not

also summarize it at full length.

• Usage section = the actual interaction shape (real commands/prompts/code),

copy-pasteable. Show CLI invocations with output when the project is a CLI.

• Compress deep detail into tables (consumers pattern-match tables faster

than prose); push the prose version to the reference doc and link it.

• Every factual claim you carry forward, re-verify against the code. Never

copy the old README's claims on faith.

• When tests pin wording: reshape the test to assert the requirement

(ordering of two install paths, presence of a link) instead of the document's shape (exact heading strings, a file list). Most contributing guides require justifying changed assertions in the PR description — write that section. Do not silently weaken a test to make the docs pass.

• Author preferences beat checklist purity. Decorative elements the author

likes (star-history charts, badges, wordmarks) stay unless the author explicitly agrees to cut them. Ask before deleting anything purely decorative; the checklist serves the author, not the reverse.

Translated READMEs

• 意译, not 直译. Rewrite in the target language's tech-writing rhythm;

restructure sentences freely. Sentence-by-sentence mapping always produces translationese ("索引进", "服务两类读者", "综合缓存").

• Keep terms in English where the community actually uses English (provider,

agent, session, tool call). Translate what has a real native term.

• Mirror structure exactly: same sections, same tables, same links, same

heading count — parity must be mechanically checkable.

• Cross-link at the top of both files (English · 中文).
• Match the product's voice. If the product's own examples are colloquial,

the README may be too ("用人话回答").

• Chinese section anchors change when headings do — update in-file anchor

links to match the new headings.

Verification before delivery

• Check every relative link and asset resolves (a quick script over

](…), src=, srcset= targets is enough).

• Run every test that reads the README or CONTRIBUTING — not just the suite

you expect to matter.

• Re-read the final README as a stranger, top to bottom, and note where you

would bail. If the bail points come in the wrong order, the funnel is wrong.

• Report the change as decisions: what moved where, what was dropped and why,

which assertions changed. A README rewrite reviewed as prose diff is hard to approve; reviewed as a decision list it is easy.