Back to Details

readme-optimization

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

README Optimization

README 优化

You are working on the single page that decides whether a developer tries a project or closes the tab. Diagnose the existing README against evidence, then rewrite it so a stranger can evaluate the project quickly and accurately - including deciding not to use it, which is a correct outcome you should never optimize away.
A README is not a documentation type. It is a landing page and a router: it answers what and why in seconds, then sends the reader onward. Judge it on whether it converts a visitor into a trial, not on documentation completeness.
Put the rewrite budget where the scarcity is. Across 393 sampled GitHub repositories (Prana et al. 2019, cited in ./references/published-findings.md; the sample is late-2010s, read it as a baseline, not a census):
  • What the project is: 97.0% - table stakes.
  • How to use it: 88.5% - table stakes.
  • Why to pick it over the alternatives: 25.7% - scarce.
  • What state the project is in: 21.4% - scarce.
Those two scarce categories are exactly what an evaluating developer must answer before adopting anything.
Stay inside this page and its repository furniture - the description, website link, topics, and social preview that surround the file. When the user's real problem is a docs site, a getting-started page, the contribution path, release notes, a launch, or a profile README, route them to the sibling skill under Reference instead of stretching the README to cover it.
你正在处理的那个页面，决定了开发者是会试用项目还是直接关闭标签页。先基于证据诊断现有 README，然后重写，让一个陌生人能够快速、准确地评估项目——包括决定_不_使用它，这是一个正确的结果，你永远不应试图优化掉。
README 不是一种文档类型。它是一个落地页和路由器：在几秒内回答“是什么”和“为什么”，然后把读者导向下一步。判断它的标准是能否把访问者转化为试用者，而不是文档完整性。
把重写预算投在稀缺之处。在 393 个采样 GitHub 仓库中（Prana et al. 2019，引用自 ./references/published-findings.md；样本来自 2010 年代末，请将其视为基线，而非普查）：
  • 项目是什么：97.0% —— 入场门槛。
  • 如何使用：88.5% —— 入场门槛。
  • 为什么选择它而不是替代品：25.7% —— 稀缺。
  • 项目处于什么状态：21.4% —— 稀缺。
这两个稀缺类别，恰恰是评估中的开发者在采纳任何东西之前必须回答的问题。
请留在该页面及其仓库门面内——即围绕该文件的 description、网站链接、topics 和社交预览。当用户的真正问题是文档站、入门页、贡献路径、发布说明、发布活动或个人主页 README 时，请将他们引导到 Reference 下的同级技能（sibling skill），而不是把 README 拉长去覆盖它。

Folklore statistics to refuse

应当拒绝的民间统计数字

Never repeat these folklore statistics in your own reasoning or to the user - all three circulate widely on invented attributions:
  • "repos with detailed READMEs get 50% more contributions"
  • "a star-history chart lifts star conversion ~15%"
  • "62% of top repos have GIF demos"
When a user cites one, say it is unsourced rather than building on it. Every figure this skill does quote is cited in ./references/published-findings.md; read it before repeating a statistic to a user.
Promise a better-evaluated project, never a percentage lift.
不要在自己的推理中或向用户重复这些民间统计数字——这三条都因虚构的出处而广泛流传：
  • “有详细 README 的仓库能多获得 50% 的贡献”
  • “star 历史图能把 star 转化率提升约 15%”
  • “62% 的顶级仓库都有 GIF 演示”
当用户引用其中一条时，请说明它没有出处，而不是以此为基础。本技能引用的每一个数字都在 ./references/published-findings.md 中有出处；在向用户重复任何统计数据之前，请先阅读该文件。
承诺“让项目被更好地评估”，而不是“带来百分之多少的提升”。

Invocation examples and output shape

调用示例与输出形态

Typical requests:
  • "audit the README of this repo"
  • "our GitHub gets traffic but no installs"
  • "rewrite the top of our README before launch"
  • "make our README readable by someone evaluating us for their company"
Every run produces a scorecard first, in this shape, before any prose is written:
README audit - acme/flowmatic   (audience: solo developer)
Band A: A1 pass · A2 FAIL (install needs Node >=20, undocumented) · A3 FAIL · A4 pass · A5 pass
Verdict: does not pass - A2 and A3 blocking; B1 returns the most per hour spent
The rewrite follows only after the user agrees with that diagnosis. The full report format, including the claim check, Band B, and the fix order, is in ./references/audit-scorecard.md.
典型请求：
  • “审计这个仓库的 README”
  • “我们的 GitHub 有流量但没人安装”
  • “发布前重写我们 README 的顶部”
  • “让为我们公司做评估的人能读懂我们的 README”
每次运行都会先产生一张如下形态的记分卡，然后再写任何正文：
README audit - acme/flowmatic   (audience: solo developer)
Band A: A1 pass · A2 FAIL (install needs Node >=20, undocumented) · A3 FAIL · A4 pass · A5 pass
Verdict: does not pass - A2 and A3 blocking; B1 returns the most per hour spent
只有在用户同意该诊断后，才进行重写。完整报告格式，包括声明核查、Band B 和修复顺序，见 ./references/audit-scorecard.md。

Interview

访谈

Ask one question at a time, multiple-choice where you can, and skip anything you can determine yourself by reading the repository. Questions 1-4 gate the rewrite - do not draft prose before they are answered.
  1. Which repository, and can I read it and run commands in it?
  2. What is the project: library or SDK, CLI tool, application or service, framework or platform, or template and learning resource?
  3. Who lands on this page: developers in one language ecosystem, polyglot developers, platform or ops engineers, or non-developer evaluators such as security and procurement?
  4. How does adoption happen - an individual developer installs it and decides alone, or a company adopts it and someone else approves the licence, the security posture, and the support story? Both is a valid answer, and it changes the middle of the page.
  5. What outcome do you want more of: installs, contributors, stars, hiring signal, enterprise conversations, or fewer repetitive support questions?
  6. What is the honest project status: experimental, actively maintained, stable and feature-frozen, or seeking maintainers?
  7. Which alternatives do readers arrive already knowing? What do those do better than you?
  8. What must appear for legal or policy reasons - licence terms, trademark notice, export or compliance statements, employer disclosure?
  9. Is there existing brand material - a logo, a tagline, a positioning sentence used on a website - that the README should match?
  10. Is the README also published elsewhere: a package registry page, a mirror, a docs-site landing page? Each render target has different rules.
  11. Is there a date this has to be done by - a launch, a conference, a funding conversation - or is the page just overdue?
  12. Do you want a one-off win before that date, or an asset that keeps paying: a positioning sentence and a page shape you reuse for the next two years?
  13. What is your ceiling - an afternoon, a week of someone's time, permission to ask customers for a logo, appetite for a governance or foundation commitment you cannot easily undo?
Answers 11-13 re-rank every ordering below; say which answer moved which fix when presenting the plan.
  • Hard date (Q11) - promotes the fixes that land in an hour, drops the funnel restructure from this pass.
  • Compounding mandate (Q12) - promotes the differentiation paragraph and the restructure, whose one-liner propagates into the registry page, the launch post, and every link unfurl.
  • Low ceiling (Q13) - deletes the terminal demo and the enterprise signals outright, rather than parking them at the bottom of a list.
If the user cannot answer 7, treat that as a finding rather than a blocker. A maintainer who cannot name their alternatives usually has a README that cannot differentiate either, and that is the most valuable thing you will fix.
一次只问一个问题，尽可能用选择题，并且跳过那些你通过阅读仓库就能自己确定的内容。问题 1-4 是重写的门禁——在回答这些问题之前，不要起草任何正文。
  1. 是哪个仓库？我可以阅读它并在其中运行命令吗？
  2. 这个项目是什么：库或 SDK、CLI 工具、应用或服务、框架或平台，还是模板与学习资源？
  3. 谁会落到这个页面：单一语言生态的开发者、多语言开发者、平台或运维工程师，还是非开发者评估者（如安全和采购）？
  4. 采用是如何发生的——单个开发者安装并独自决定，还是公司采用并由其他人批准许可证、安全态势和支持故事？两者都是有效答案，它会改变页面的中间部分。
  5. 你更希望获得什么结果：安装量、贡献者、star、招聘信号、企业对话，还是更少的重复性支持问题？
  6. 项目诚实的状态是什么：实验性、积极维护、稳定且冻结特性，还是在寻找维护者？
  7. 读者到达之前已经知道哪些替代品？那些替代品在哪里比你做得好？
  8. 出于法律或政策原因必须出现什么——许可证条款、商标声明、出口或合规声明、雇主披露？
  9. 是否已有品牌素材——logo、标语、网站上使用的定位句——README 应当与之匹配？
  10. README 是否也发布在其他地方：包注册表页面、镜像、文档站落地页？每个渲染目标都有不同的规则。
  11. 是否有必须完成的日期——发布、会议、融资对话——还是这个页面只是逾期未处理？
  12. 你想要的是一次性的胜利，还是一个能持续带来收益的资产：一句定位语和一个未来两年可复用的页面形态？
  13. 你的上限是什么——一个下午、某人一周的时间、向客户索要 logo 的许可、对一项你无法轻易撤销的治理或基金会承诺的意愿？
答案 11-13 会重新排序下方的所有优先级；在呈现计划时，说明哪个答案调整了哪个修复。
  • 硬日期（Q11）——提升一小时内能落地的修复，从本轮中删掉漏斗重构。
  • 复利任务（Q12）——提升差异化段落和重构，因为其一句话定位会传播到注册表页面、发布帖和每一次链接展开预览。
  • 低上限（Q13）——直接删除终端演示和企业信号，而不是把它们放在列表底部。
如果用户无法回答第 7 题，把它当作一个发现，而不是阻碍。一个说不出自己替代品的维护者，通常也有一个无法差异化的 README，而那是你将修复的最有价值的东西。

Step 1 - Declare the audience, then check the README is the bottleneck

第 1 步——声明受众，然后确认 README 是瓶颈

Answer 4 decides the whole audit. The enterprise evaluator and the solo developer want structurally different content, and optimizing for one degrades the other: a hobbyist bounces off a wall of compliance badges, and a procurement reader distrusts a page with no security or governance signal. Write the declared audience at the top of your scorecard so every later judgement is checkable against it.
Then confirm the README is what is broken. If the code host exposes traffic data, take unique visitors and clones for the last two weeks.
  • Decent traffic with a clone-to-visitor ratio of only a few percent: this is the case this skill is for - people arrive and leave unconvinced.
  • Few visitors in the first place: a distribution problem, not a prose problem - route the user to launch or distribution work instead of rewriting a page almost nobody reads.
That "few percent" boundary is a working heuristic, not a benchmark; on a borderline number, look at referrers rather than ruling.
答案 4 决定整个审计。企业评估者和独立开发者想要结构上不同的内容，为其中一个优化会损害另一个：爱好者会被一堵合规徽章墙劝退，而采购读者会不信任一个没有安全或治理信号的页面。把声明的受众写在记分卡顶部，这样之后的每个判断都可以对照它来核查。
然后确认 README 是否就是问题所在。如果代码托管平台暴露了流量数据，取最近两周的独立访客数和 clone 数。
  • 流量尚可，但 clone 与访客之比只有几个百分点：这正是本技能适用的场景——人们来了，却又没有被说服地离开。
  • 一开始访客就很少：这是分发问题，而不是文案问题——把用户引向发布或分发工作，而不是重写一个几乎没人读的页面。
“几个百分点”这个边界是一个工作启发式，不是基准；在临界数字上，看来源（referrers）而不是直接下结论。

Step 2 - Gather evidence

第 2 步——收集证据

Never audit from memory of what good READMEs look like.
  1. Read the README in full and note where you personally got confused. Your first-read confusion is the closest thing you have to a cold reader.
  2. Run the mechanical audit: 
    scripts/readme-audit.sh <repo-root>
    . It reports:
    • shadowed copies
    • truncation risk
    • the heading tree
    • section count against the median of 7
    • words before the first copyable command
    • badge count
    • missing alt text
    • registry-hostile raw HTML
    • broken relative links
    • placeholder text
    • missing content categories
  3. Read the repository around the README: manifests for the real runtime requirements, the licence file, recent commit dates, open-issue volume, and whether the examples it references exist on disk.
  4. If your environment can browse the web, open the project's package-registry page and compare it to the code-host render. Relative links and raw HTML frequently break there, and that page is often the higher-traffic one.
  5. If your environment has persistent memory, reuse any stored positioning statement, audience definition, or competitor list for this project instead of re-deriving it.
Optionally add a structural README scorer and the code host's community-standards checklist as a second opinion, treating both as hygiene baselines - see the validity ceiling in ./references/tooling-and-measurement.md. The script reports facts, not judgements: a section count of 25 is a question to answer, not a verdict.
绝不要凭“好 README 长什么样”的记忆来审计。
  1. 完整阅读 README，并记下你自己在哪里感到困惑。你初次阅读时的困惑，是你最接近冷读者（cold reader）的东西。
  2. 运行机械审计：
    scripts/readme-audit.sh <repo-root>
    。它会报告：
    • 被遮蔽的副本（shadowed copies）
    • 截断风险
    • 标题树
    • 与中位数 7 相比的章节数量
    • 第一个可复制命令之前的字数
    • 徽章数量
    • 缺失的 alt 文本
    • 对注册表不友好的原始 HTML
    • 损坏的相对链接
    • 占位符文本
    • 缺失的内容类别
  3. 阅读 README 周围的仓库：manifest 中真实的运行时要求、许可证文件、最近的提交日期、未解决问题数量，以及它引用的示例是否真的存在于磁盘上。
  4. 如果你的环境可以访问网络，打开项目的包注册表页面，并与代码托管平台的渲染结果对比。相对链接和原始 HTML 经常在那里出问题，而且那个页面往往是流量更高的。
  5. 如果你的环境有持久记忆，直接复用它保存过的定位陈述、受众定义或竞争对手列表，而不是重新推导。
可以额外添加一个结构化 README 评分器和代码托管平台的社区标准清单作为第二意见，把两者都视为卫生基线——参见 ./references/tooling-and-measurement.md 中的有效性上限。脚本报告的是事实，不是判断：章节数为 25 是一个需要回答的问题，而不是一个结论。

Step 3 - Score the current README

第 3 步——为当前 README 打分

Work through ./references/audit-scorecard.md and produce the scorecard in the shape above.
  • Band A: five blocking checks - identity, the install actually running, every claim verifiable, honest status, reachable licence.
  • Band B: eight scored checks, worth two points each.
Attach evidence to every check - a line number, a quoted sentence, or the terminal output of a command you ran. Get the user's agreement on the score before rewriting anything: a maintainer who rejects the diagnosis rejects the treatment, and they are sometimes right, since a constraint invisible from the repository can justify a check you scored zero.
按照 ./references/audit-scorecard.md 逐项执行，并生成上面形状的记分卡。
  • Band A：五个阻塞性检查——身份识别、安装真的能跑、每条声明都可验证、诚实的状态、可触达的许可证。
  • Band B：八个计分检查，每项两分。
为每个检查附上证据——行号、引用的句子，或你运行命令后的终端输出。在重写任何内容之前，先让用户同意这个分数：一个拒绝诊断的维护者也会拒绝治疗，而且他们有时是对的，因为一个从仓库中看不到的约束，可能足以证明你打了零分的某项检查是合理的。

Order the fixes

排列修复顺序

Order the fix list by what each fix returns per hour spent, not by how easy it is to write and not by how much damage it undoes - those three orderings disagree, so state all of them and lead with the third:
  • effort, least first: 
    status line == badge row > claim check > install path > differentiation paragraph > funnel restructure
  • value, most first: 
    install path > differentiation paragraph > claim check > status line > funnel restructure > badge row
  • efficiency, do first: 
    status line > install path > claim check > differentiation paragraph > badge row > funnel restructure
The status line and the badge row tie on effort: each is one edit to one block, written from what the maintainer already knows, verified against nothing - no command run, no source read. They separate on value, since a status line answers a question only 21.4% of READMEs answer and a badge row answers one 61% of contributors ignore.
Default to the top three for a first pass; move down once the blocking checks are green, or when the cold-reader test fails on a question none of the three touches.
The funnel restructure loses every round - a week against fixes that land in an hour - so this order under-invests in the one change that makes the page work. Promote it when the cold reader answers wrong because they never scrolled far enough, or when a launch is the reason for the audit, and say you are promoting it against the ratio.
The ordering is a default, not a law, and it shifts with who executes it. Re-rank it against what you already know:
  • A maintainer who can name their alternatives in one sentence gets the differentiation paragraph nearly free, which promotes it above the install path.
  • A project with no install command - a spec, a dataset, a template - deletes that row rather than scoring it zero forever.
Delete every fix answer 13's ceiling rules out instead of listing it last.
按每项修复每小时返回的价值来排列修复清单，而不是按写起来有多容易，也不是按它能挽回多少损害——这三个排序会互相冲突，所以请把三者都说出来，并用第三种作为引导：
  • 努力程度，从最少开始：
    status line == badge row > claim check > install path > differentiation paragraph > funnel restructure
  • 价值，从最多开始：
    install path > differentiation paragraph > claim check > status line > funnel restructure > badge row
  • 效率，先做：
    status line > install path > claim check > differentiation paragraph > badge row > funnel restructure
状态行和徽章行在努力程度上并列：各自都只是对一个区块的一次编辑，写的是维护者已经知道的东西，不需要对照任何东西验证——不用运行命令，不用读源码。它们会在价值上分开，因为状态行回答的是只有 21.4% 的 README 回答的问题，而徽章行回答的是 61% 的贡献者都会忽略的问题。
第一轮默认做前三个；一旦阻塞性检查变绿，或者当冷读者测试在一个前三项都未触及的问题上失败时，再往下做。
漏斗重构每一轮都会落败——一周的工作对上那些一小时内就能落地的修复——所以这个顺序对“让页面真正起作用”的那一个改动投资不足。当冷读者因为从未滚动到足够下方而答错，或者当审计的起因是发布活动时，把它提前，并说明你是基于这个比值把它提前的。
这个顺序是默认值，不是法则，它会随执行者而变。根据你已经知道的情况重新排序：
  • 一个能一句话说出自己替代品的维护者，几乎可以免费获得差异化段落，这会让它排在安装路径之上。
  • 一个没有安装命令的项目——如规范、数据集、模板——应删掉那一行，而不是永远给它打零分。
删除第 13 题上限所排除的每一项修复，而不是把它列在最后。

Step 4 - Verify every claim against the source

第 4 步——对照源码验证每一条声明

A README is a set of claims about a codebase, and every claim is checkable. Agents and maintainers alike write from memory of how an API usually looks; a reader cannot tell a verified line from an invented one, and you can, because you have the repository.
List every claim:
  • command
  • flag
  • default value
  • environment variable
  • config key
  • endpoint
  • exported symbol
  • file path
  • version requirement
  • behavioural assertion hidden in a verb, e.g. "automatically reconnects", "retries three times", "case-insensitive"
Verify each against its own source of truth - the argument parser, the definition site, the route table, the changelog - by reading it, not recalling it. A flag documented in the README but absent from the parser is a hallucination, not a typo.
Then run the install path itself, because it catches the most real damage:
  1. Start from a clean state - a container, a fresh virtual environment, a temporary directory, whatever your environment supports. If you cannot execute commands, say so plainly and ask the user to run the sequence and paste the output; never mark this check passed on inspection.
  2. Execute the documented install command exactly as written, then the first usage example exactly as written.
  3. Record every gap: an undocumented runtime version, a system package assumed present, a required environment variable, an output that differs from the README.
  4. Fold each gap into the README as an explicit prerequisite or a verification step, then run the sequence again from clean.
Repeat until the documented path runs end to end with no undocumented step. Any performance number, compatibility matrix, scale limit, or "production ready" claim needs a source inside the repository - a benchmark script, a CI matrix, a changelog entry - or it comes out. When you cannot verify something, downgrade the claim to what you can verify and say which part is unconfirmed.
README 是一组关于代码库的声明，而每一条声明都是可核验的。Agent 和维护者都会凭“API 通常长什么样”的记忆来写作；读者无法分辨一行已核验的代码和一行编造的代码，但你可以，因为你拥有仓库。
列出每一条声明：
  • 命令
  • 标志
  • 默认值
  • 环境变量
  • 配置键
  • 端点
  • 导出的符号
  • 文件路径
  • 版本要求
  • 隐藏在动词中的行为断言，例如“自动重连”、“重试三次”、“不区分大小写”
针对每一条，用其自己的事实来源——参数解析器、定义处、路由表、变更日志——通过阅读来核验，而不是回忆。README 中写了但解析器里没有的 flag，是幻觉，不是笔误。
然后亲自运行安装路径，因为它能抓住最实际的损害：
  1. 从干净状态开始——容器、全新的虚拟环境、临时目录，你的环境支持什么就用什么。如果你不能执行命令，请直说，并请用户运行该序列并粘贴输出；绝不要仅凭检查就标记此检查通过。
  2. 完全按照文档中写的运行安装命令，然后完全按照写的运行第一个用法示例。
  3. 记录每一个差距：未记录的运行时版本、假定存在的系统包、必需的环境变量、与 README 不同的输出。
  4. 把每个差距作为显式前置条件或验证步骤纳入 README，然后从干净状态再次运行该序列。
重复，直到文档化的路径在没有未记录步骤的情况下端到端运行。任何性能数字、兼容性矩阵、规模限制或“生产就绪”声明，都需要仓库内的来源——基准脚本、CI 矩阵、变更日志条目——否则就删掉。当你无法验证某件事时，把声明降级为你所能验证的部分，并说明哪一部分未经确认。

Step 5 - Choose the shape, then rewrite section by section

第 5 步——选择形态，然后逐节重写

Pick the skeleton from ./references/readme-skeletons.md that matches what the reader is deciding, not what the code happens to be.
  • A library reader is judging fit with an existing codebase.
  • A CLI reader is comparing against a tool already installed.
  • A framework reader is making a multi-year bet.
Order sections by how quickly each lets a reader disqualify the project. This is cognitive funneling, named by Kira in Art of README: widest and most disqualifying information first, narrowing to detail only a committed reader reaches. One consequence: a non-permissive licence belongs near the top, because it disqualifies fastest and hiding it wastes the reader's time.
Before writing, brainstorm the positioning explicitly instead of reaching for the first phrasing. Draft three candidate one-liners on different axes:
  • what it does mechanically
  • what problem it removes
  • what it lets you stop using
Present them with each one's trade-off and your recommendation, and let the user choose. The one-liner propagates into the repository description, the registry page, and every link unfurl.
Draft one section at a time and get agreement before moving on; per-section approval surfaces a disagreement while it is still cheap to fix. For each section:
  1. Write the shortest version that answers its question completely.
  2. Replace every unfalsifiable claim ("simple", "blazing fast", "developer-friendly") with something a reader could check - a number, a dependency count, a supported-platform list, a named trade-off.
  3. Link every term a reader outside the project's immediate ecosystem might not know.
  4. State what the project deliberately does not do, and when to use something else. This is the highest-trust sentence in most READMEs and it costs one line.
  5. Move anything that grew past a screen into a linked document and leave a one-line pointer behind. Relocate overflow, never delete it.
Keep community health content out of the file - contribution guidelines, code of conduct, security disclosure, support policy. Each belongs in its own recognized file, which the code host surfaces at the moment it matters; inlining them only adds scroll distance before the reader can decide anything. One exception: the licence file must ship inside the repository, so an organization-level default is not enough.
Run the finished prose through your preferred humanizer skill before presenting it. Copy that reads as generated undermines the credibility the rest of the page is building, and developers spot it easily.
See ./references/before-after-examples.md for worked positive and negative examples of the opening lines, the differentiation section, the status statement, badge rows, install blocks, and usage snippets.
从 ./references/readme-skeletons.md 中选择与读者正在_做决定_的内容相匹配的骨架，而不是与代码碰巧是什么相匹配。
  • 库的读者在判断与现有代码库的契合度。
  • CLI 的读者在与已安装的工具做比较。
  • 框架的读者在下一次多年的赌注。
按“每个部分能让读者多快淘汰这个项目”来排列章节顺序。这就是认知漏斗（cognitive funneling），由 Kira 在《Art of README》中命名：最宽泛、最能排除的信息放在最前，收窄到只有坚定的读者才会到达的细节。一个推论：非宽松许可证应该放在靠近顶部的位置，因为它淘汰得最快，隐藏它会浪费读者的时间。
在写作之前，显式地进行定位头脑风暴，而不是伸手抓第一个措辞。在三个不同轴向上起草三个候选一句话定位：
  • 它在机制上做什么
  • 它消除了什么问题
  • 它能让你停止使用什么
把它们各自的权衡和你的推荐一起呈现出来，让用户选择。这句一句话定位会传播到仓库 description、注册表页面和每一次链接展开预览。
一次起草一个部分，在继续之前获得同意；逐节审批会让分歧在仍然便宜解决的时候浮出水面。对于每个部分：
  1. 写出能完整回答其问题的最短版本。
  2. 把每一个不可证伪的声明（“简单”、“极快”、“开发者友好”）替换成读者可以核查的东西——一个数字、依赖数量、支持的平台列表、一个被指名的权衡。
  3. 为项目直接生态之外的读者可能不知道的每个术语添加链接。
  4. 说明这个项目刻意不做的事，以及什么时候该用别的东西。这是大多数 README 中最能建立信任的一句话，而它只占一行。
  5. 任何超过一屏的内容，移到链接文档中，并留下一行指针。移动溢出的内容，绝不删除。
不要把社区健康内容塞进文件里——贡献指南、行为准则、安全披露、支持政策。每项都属于各自被认可的独立文件，代码托管平台会在关键时刻展示它们；把它们内联只会增加读者在能做出任何决定之前的滚动距离。一个例外：许可证文件必须随仓库一起发布，所以组织级默认还不够。
在呈现之前，用你偏好的 humanizer 技能处理完成的文本。读起来像 AI 生成的文案会破坏页面其余部分正在建立的信任，而开发者很容易看出来。
参见 ./references/before-after-examples.md，其中包含开头行、差异化部分、状态声明、徽章行、安装块和用法示例的正反示例。

Step 6 - Calibrate badges to the evidence

第 6 步——根据证据校准徽章

Badges are the one README element with a rigorous evidence base: Trockman et al. studied 294,941 npm packages (ICSE 2018). Use the study's distinction rather than taste.
  • Keep assessment signals - badges backed by a third-party check that cannot pass unless the underlying thing is true: CI status, coverage, published version, dependency freshness.
  • Cut conventional signals - badges that merely state an intent, such as "PRs welcome", with nothing verifying them. They signal nothing.
  • Cap the row. Among already-popular packages, excessive badge use correlates with decreased popularity, and adopting a badge does not raise popularity at all - popular projects are simply likelier to have badges. The direction is sourced; the cap of four is a working default here, not a published figure, so justify each survivor by the reader question it answers rather than arguing about the number.
  • Expect the maintainer to over-value them. The study's small companion survey found maintainers rate badges as a quality indicator far more often than contributors do, and most contributors say badges do not influence them at all. Quote the figures from ./references/published-findings.md when a maintainer resists cutting the row.
徽章是 README 唯一一个有严谨证据基础的元素：Trockman 等人研究了 294,941 个 npm 包（ICSE 2018）。用研究的区分，而不是个人品味。
  • 保留评估信号（assessment signals）——由第三方检查支持、且只有基础事实为真时才能通过的徽章：CI 状态、覆盖率、已发布版本、依赖新鲜度。
  • 删掉惯例信号（conventional signals）——只是表达意图、没有任何东西验证的徽章，例如“欢迎 PR”。它们什么都说明不了。
  • 限制徽章行数。在已经流行的包中，过度使用徽章与流行度_下降_相关，而采用徽章根本不会提高流行度——流行项目只是更可能有徽章而已。方向是有出处的；四枚的上限在这里是工作默认值，不是已发表的数字，所以用“它回答了读者的哪个问题”来为每个幸存者辩护，而不是争论数字本身。
  • 预期维护者会高估它们。研究附带的小型调查发现，维护者把徽章当作质量指标的比例远高于贡献者，而大多数贡献者说徽章对他们完全没有影响。当维护者不愿删行时，引用 ./references/published-findings.md 中的数字。

Step 7 - Fix repository furniture and render mechanics

第 7 步——修复仓库门面与渲染机制

Three things compete for this step's budget, and they are not close:
  • efficiency, do first: 
    furniture > render mechanics > terminal demo
  • Furniture is near-zero effort and buys the only text a reader sees before opening the repository: the description, website link and topics are what search listings carry, and the social preview is what unfurls when someone pastes the link into a chat.
  • Render mechanics cost about an hour and buy the page working for readers who never see the code host's render - registry pages, terminals, screen readers.
  • Terminal demo costs a week to produce well and then becomes a standing job, going stale whenever the output changes.
The demo is what this order starves, and it is the highest-value element on the page for a CLI or a visual tool, where the output is the product. Promote it above render mechanics in exactly that case, and generate it from a script rather than hand-recording it, so re-rendering stays cheap enough to survive as a standing job. Delete it for a library with no visible output - a demo of an import statement earns nothing - rather than leaving it to reappear as scope later.
Fix the furniture, then fix how the file itself renders:
  1. Give every image alt text, and move any instruction, command, or decision-relevant fact out of screenshots and animated demos into text. Readers meet READMEs in terminals, on registry pages that strip HTML, and through screen readers - an animated demo is invisible to all three.
  2. Delete a hand-written table of contents - code hosts generate an outline from headings, and the manual copy goes stale.
  3. Check that relative links resolve from the repository root on the default branch, and that the page still reads correctly where raw HTML is stripped.
  4. Keep only one rendered README. Where a host renders a 
    .github/
    copy in preference to the root file, the root copy is what registries and mirrors publish, so the two silently diverge.
  5. In a monorepo, make the root README a router to the per-package READMEs rather than covering every package inline.
When the demo does earn its place, keep it short, high-contrast and legible at embed scale, and place it right after the tagline. Treat its conversion benefit as practitioner consensus rather than a measured result - no study prices it, which is another reason not to let it outrank the two cheaper rows by default.
有三件事竞争这一步的预算，而且差距不小：
  • 效率，先做：
    furniture > render mechanics > terminal demo
  • 门面（Furniture） 几乎是零成本，买下的是读者在打开仓库之前唯一能看到的文本：description、网站链接和 topics 是搜索结果列表携带的内容，社交预览是有人把链接粘贴到聊天中时展开的内容。
  • 渲染机制（Render mechanics） 花费大约一小时，买下的是页面在那些永远看不到代码托管平台渲染结果的读者面前正常工作——注册表页面、终端、屏幕阅读器。
  • 终端演示（Terminal demo） 做好需要一周，然后成为一个常设工作，每次输出变化都会过时。
演示正是这个顺序所饿死的元素，而对于 CLI 或可视化工具来说，它又是页面上价值最高的元素——因为输出_就是_产品。恰恰在这种情况下降它提升到渲染机制之上，并且用脚本生成而不是手工录制，这样重新渲染的成本足够低，能作为一个常设工作存续。对于没有可见输出的库，删除它——一个 import 语句的演示赚不到任何东西——而不是留着它以后作为范围蔓延重新出现。
先修门面，再修文件本身的渲染：
  1. 给每张图片加上 alt 文本，并把任何说明、命令或与决策相关的事实从截图和动画演示移到文本中。读者会在终端、剥离 HTML 的注册表页面以及屏幕阅读器中遇到 README——动画演示对这三者都不可见。
  2. 删除手写的目录——代码托管平台会从标题生成大纲，手动副本会过时。
  3. 检查相对链接是否能在默认分支的仓库根目录解析，以及在原始 HTML 被剥离的地方页面是否仍然能正确阅读。
  4. 只保留一个渲染 README。如果某个平台优先渲染 
    .github/
    中的副本而不是根文件，注册表和镜像发布的是根副本，两者会悄然分叉。
  5. 在 monorepo 中，让根 README 成为各包 README 的路由器，而不是内联覆盖每一个包。
当演示确实值得保留时，保持简短、高对比度，并在嵌入尺寸下清晰可读，放在标语之后。把它的转化收益视为从业者共识，而不是测量结果——没有研究给它定价，这也是为什么默认情况下不该让它压过那两个更便宜的行。

Step 8 - Add enterprise trust signals, only if the audience calls for them

第 8 步——仅当受众需要时，添加企业信任信号

Run this step only when Step 1 declared a company or procurement audience.
An enterprise decision-maker optimizes for defensibility, not best technical fit, so recognizable third-party signals - a foundation tier, an audit, an attestation, a well-known adopter - outperform novel claims. Published evaluation checklists weight maintenance activity, licence clarity and security posture above presentation quality; sources are in ./references/published-findings.md.
Six signals are available, spanning two orders of magnitude in what they cost:
  • effort, least first: 
    support expectation == release cadence > security policy > named adopters == supply-chain attestation > governance and maintainer depth > foundation affiliation
  • value, most first: 
    foundation affiliation > named adopters > security policy > governance and maintainer depth > supply-chain attestation > release cadence == support expectation
  • compliance cost:
    • foundation affiliation demands trademark or IP assignment and a legal sign-off you cannot walk back
    • named adopters need each company's own marketing approval, revocable but only by asking again
    • a security policy commits you publicly to a response window you then have to honour
    • the remaining three trigger no review and are reversible with one commit
  • efficiency, do first: 
    support expectation == release cadence > security policy > named adopters > governance and maintainer depth > supply-chain attestation > foundation affiliation
Support expectation and release cadence tie twice over: each is one sentence stating something already true, needing nobody's permission and no work beyond reading the commit log. Named adopters and supply-chain attestation tie on effort at about a week each, but separate on efficiency - the attestation persuades an engineer who was going to say yes anyway, while a recognizable logo persuades the person who signs.
Default to the first three, an afternoon between them, which clear most of what an evaluation checklist scores. Move to named adopters when a deal is in the room and someone has asked "who else runs this".
Foundation affiliation is what this order starves: strongest signal on the page, a quarter or more of work, so it never wins on ratio and a README-driven plan never reaches it. Promote it when the project is being adopted as infrastructure rather than as a dependency, or when a foundation tier is the objection you keep losing to - then hand that decision to the user, because its reversibility cost is not a documentation cost.
Delete every signal answer 13 rules out instead of listing it as future work: no legal appetite means no foundation row, and a solo maintainer writes an honest support expectation rather than an empty governance heading.
只有当第 1 步声明了公司或采购受众时，才运行这一步。
企业决策者优化的目标是可辩护性（defensibility），而不是最佳技术契合度，因此可识别的第三方信号——基金会层级、审计、证明、知名采用者——胜过新颖的声明。已发表的评估清单把维护活跃度、许可证清晰度和安全态势排在展示质量之上；来源见 ./references/published-findings.md。
有六种信号可用，成本跨越两个数量级：
  • 努力程度，从最少开始：
    support expectation == release cadence > security policy > named adopters == supply-chain attestation > governance and maintainer depth > foundation affiliation
  • 价值，从最多开始：
    foundation affiliation > named adopters > security policy > governance and maintainer depth > supply-chain attestation > release cadence == support expectation
  • 合规成本：
    • 基金会隶属关系要求商标或知识产权转让，以及一个你无法撤回的法律签字
    • 指名采用者需要每家公司自己的市场部门批准，可撤销，但只能通过再次请求
    • 安全政策公开承诺一个响应窗口，之后你必须兑现
    • 其余三项不需要任何审查，一次提交即可撤销
  • 效率，先做：
    support expectation == release cadence > security policy > named adopters > governance and maintainer depth > supply-chain attestation > foundation affiliation
支持预期和发布节奏两次并列：各自只是一句陈述已经为真之事的话，不需要任何人许可，除了读提交日志之外不需要任何工作。指名采用者和供应链证明在努力程度上并列，各约一周，但在效率上分开——证明能说服一个本来就要说“是”的工程师，而一个可识别的 logo 能说服那个签字的人。
默认做前三个，加起来一个下午，能扫清评估清单打分的绝大部分。当房间里有一笔交易、有人问“还有谁在用这个”时，再转向指名采用者。
基金会隶属关系正是这个顺序所饿死的：页面最强的信号，却要四分之一或更多的工作量，所以它永远赢不了投入产出比，而一个 README 驱动的计划永远不会触及它。当项目是被当作基础设施而不是依赖来采用，或者当你一直输给“基金会层级”这个反对意见时，把它提前——然后把决定交给用户，因为它的可逆成本不是文档成本。
删除第 13 题排除的每一个信号，而不是把它列为未来工作：没有法律意愿就意味着没有基金会行，而独立维护者写的是诚实的支持预期，而不是一个空的治理标题。

Step 9 - Re-score and test with a cold reader

第 9 步——重新打分并用冷读者测试

Re-run the scorecard. The README passes when all five blocking checks pass and the scored checks total at least 14 of 16 - a working default here rather than a published bar, so let the user move it for a stated reason you record in the report.
Then run the cold-reader test defined in the scorecard - five questions, 60 seconds, five correct answers to pass - using a person if the user can find one, otherwise a fresh agent session with no repository context. Each wrong answer maps to a specific check, so a failure tells you exactly what to fix.
If your environment has persistent memory, store the agreed one-liner, audience definition, competitor list, and final score. Sibling work - launch posts, docs landing pages, conference abstracts - should start from that positioning rather than inventing a new one.
重新运行记分卡。当全部五个阻塞性检查通过，且计分检查总计至少 16 分中的 14 分时，README 才算通过——这是这里的工作默认值，不是已发表的标准，所以如果用户提出有记录在报告中的理由，允许他们移动这个标准。
然后运行记分卡中定义的冷读者测试——五个问题、60 秒、五个正确回答才能通过——如果用户能找到真人就用真人，否则用一个没有仓库上下文的全新 agent 会话。每个错误答案都对应到一个具体检查，所以失败会精确告诉你该修什么。
如果你的环境有持久记忆，存储已达成一致的一句话定位、受众定义、竞争对手列表和最终分数。同级工作——发布帖、文档落地页、会议摘要——应该从那个定位出发，而不是发明一个新的。

What to track afterwards

之后要追踪什么

Attribution on a README is weak. Record the ship date, compare a full period before against a full period after, and annotate confounders instead of claiming the delta. Re-measure four to six weeks out; shorter windows are noise.
  • efficiency, track first: 
    support load > conversion rate > contributor conversion
  • Support load costs nothing to track and moves within weeks: count the "how do I install this" and "what does this do" issues per month and watch them fall.
  • Conversion rate - clones or downloads divided by unique visitors - takes an hour to assemble from the host's traffic data and is the truest single number available, but says nothing until a full period has passed either side.
  • Contributor conversion is slowest and most confounded; read it a quarter out.
Drop stars from the tracking plan entirely, even when answer 5 named stars as the goal: they only ever go up, so the metric cannot show a regression and reports success for a change that made the page worse. Offer the conversion rate instead.
If clones rise but contributor count does not, the contribution path is broken, not the README. Measurement surfaces and their caveats: ./references/tooling-and-measurement.md.
README 的归因很弱。记录上线日期，将完整的“之前”周期与完整的“之后”周期进行比较，并标注混淆变量，而不是声称这个差值。四周到六周后再重新测量；更短的窗口只是噪声。
  • 效率，先追踪：
    support load > conversion rate > contributor conversion
  • 支持负担（Support load） 追踪成本为零，而且几周内就会变化：统计每月“我该怎么安装这个”和“这是做什么的”问题数量，看着它们下降。
  • 转化率（Conversion rate）——clone 或下载量除以独立访客数——从托管平台的流量数据中整理出来需要一小时，是能得到的最真实单一数字，但在两侧都过完一个完整周期之前，它什么也说明不了。
  • 贡献者转化（Contributor conversion） 最慢，混淆因素最多；一个季度后再看。
把 star 从追踪计划中完全去掉，即使第 5 题把 star 定为目标：它们只会涨，所以这个指标无法显示回退，并且会为一个让页面变得更糟的改动报告成功。改为提供转化率。
如果 clone 上升但贡献者数量没有，那是贡献路径坏了，不是 README。测量界面及其注意事项：./references/tooling-and-measurement.md。

Common failure modes

常见失败模式

Rewriting before diagnosing. A rewrite that fixes the prose and preserves the broken install has fixed nothing. In review mode, do not rewrite at all unless asked.
Padding to look serious. Half of all READMEs sit between 5 and 12 sections, median 7. A four-section README for a single-purpose project is complete; adding architecture and roadmap sections to a 200-line utility makes it look abandoned, not mature.
Marketing voice. Superlatives without evidence read as noise to this audience and actively lower trust. Every claim should be checkable or cut.
Auditing only one render target. The registry page frequently has more traffic and different rules. A README that only works on one host is broken for a large share of its readers.
Fabricated status. Never write "production ready", "battle-tested", or a user count you did not get from the user. An overstated claim is disproved by one glance at the commit history and costs more trust than an honest "early beta".
Leading with the cheapest fix. The badge row is the fastest thing on the list and nearly the least valuable. Present the order from Order the fixes, not the order you could finish first.
先重写后诊断。 一次修复了文案却保留了坏掉的安装的重写，等于什么都没修。在审查模式下，除非被要求，否则根本不要重写。
填充以显得严肃。 一半的 README 有 5 到 12 个章节，中位数是 7。一个单用途项目的四节 README 就是完整的；给一个 200 行的工具加上架构和路线图章节，只会让它看起来被遗弃，而不是成熟。
营销腔。 没有证据的顶级形容词在这个受众看来是噪音，并且会主动降低信任。每一条声明都应该是可核查的，否则删掉。
只审计一个渲染目标。 注册表页面往往流量更大、规则也不同。一个只在一个托管平台上正常的 README，对其很大一部分读者来说就是坏的。
编造状态。 永远不要写“生产就绪”、“久经考验”，或一个你没有从用户那里得到的用户数。一句夸大的声明，只要看一眼提交历史就会被戳穿，并且比诚实的“早期测试版”损失更多信任。
用最便宜的修复打头。 徽章行是列表上最快的东西，也几乎是最没价值的。按“排列修复顺序”中的顺序呈现，而不是按你能先完成的顺序。

Reference

参考

  • ./references/audit-scorecard.md - Rubric, thresholds, cold-reader test, and report format.
  • ./references/published-findings.md - Every sourced figure and the folklore list.
  • ./references/readme-skeletons.md - Section orderings per project type.
  • ./references/before-after-examples.md - Worked positive and negative examples.
  • ./references/tooling-and-measurement.md - Scoring, linting and attribution tools.
  • ./scripts/readme-audit.sh - Mechanical facts the scorecard depends on.
  • samber/developer-relations-skills@developer-quickstart-guide - Dedicated getting-started page.
  • samber/developer-relations-skills@developer-docs-structure-audit - Documentation site structure.
  • samber/developer-relations-skills@oss-contributor-onboarding - CONTRIBUTING.md and first-contribution path.
  • samber/developer-relations-skills@changelog-writing - Release notes and changelog structure.
  • samber/developer-relations-skills@oss-launch - Launch planning and execution.
  • samber/developer-relations-skills@oss-distribution-strategy - Which channels point readers at this repository surface.
  • ./references/audit-scorecard.md —— 评分标准、阈值、冷读者测试和报告格式。
  • ./references/published-findings.md —— 所有有出处的数字和民间统计清单。
  • ./references/readme-skeletons.md —— 每种项目类型的章节排序。
  • ./references/before-after-examples.md —— 已完成的正面和反面示例。
  • ./references/tooling-and-measurement.md —— 评分、lint 和归因工具。
  • ./scripts/readme-audit.sh —— 记分卡依赖的机械事实。
  • samber/developer-relations-skills@developer-quickstart-guide —— 专门的入门页面。
  • samber/developer-relations-skills@developer-docs-structure-audit —— 文档站结构。
  • samber/developer-relations-skills@oss-contributor-onboarding —— CONTRIBUTING.md 和首次贡献路径。
  • samber/developer-relations-skills@changelog-writing —— 发布说明和变更日志结构。
  • samber/developer-relations-skills@oss-launch —— 发布规划与执行。
  • samber/developer-relations-skills@oss-distribution-strategy —— 哪些渠道会把读者引向这个仓库表面。