Back to Details

good-readme

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

good-readme

good-readme

Philosophy

设计理念

Core principle: A README is the front door to your project. It should answer "what is this, why should I care, and how do I use it?" within 30 seconds. Every section earns its place by serving a reader's real need — don't pad with boilerplate.
Good READMEs are scannable, honest, and audience-aware. They lead with a clear value proposition, show real usage examples, and respect the reader's time. A developer evaluating your project will decide in under a minute whether to invest further — the README is your pitch.
Bad READMEs are walls of text with no structure, auto-generated boilerplate nobody reads, or sparse one-liners that force readers to dig through source code. Equally bad: over-documented READMEs that duplicate what's in 
/docs
or include every API method inline.
See anatomy.md for section-by-section guidance, examples.md for patterns from well-regarded projects, anti-patterns.md for common mistakes, and cloudflare.md for Cloudflare ecosystem conventions.
核心原则：README是项目的门面，读者应该能在30秒内搞懂「这是什么、我为什么要关注、我该怎么用」。每个板块的存在都应当满足读者的实际需求——不要堆砌无意义的模板内容。
优质README具备易扫读、内容真实、适配目标受众的特点。它们开篇就明确传递价值主张，提供真实的使用示例，尊重读者的时间。评估你的项目的开发者会在一分钟内决定是否要进一步投入时间了解项目——README就是你的项目推介。
糟糕的README要么是毫无结构的大段文字、没人会看的自动生成模板，要么是过于简略的一两句话，逼得读者去翻源代码。同样糟糕的还有内容过度冗余的README：重复/docs目录下的内容，或者把所有API方法都直接写在里面。
逐板块编写指南可参考anatomy.md，优秀项目的README范例可参考examples.md，常见错误可参考anti-patterns.md，Cloudflare生态编写规范可参考cloudflare.md。

Modes

使用模式

This skill operates in two modes:
本技能包含两种使用模式：

1. Create — New README

1. 创建模式 — 全新README

For projects that have no README or need one written from scratch.
Before writing anything:
  • Read the project's source code to understand what it does
  • Identify the target audience (end users, developers, both?)
  • Check for existing docs, config files, and CI setup that reveal project conventions
  • Look at package.json / Cargo.toml / pyproject.toml / go.mod etc. for project metadata
  • Ask the user: "Who is this README for, and what's the one thing you want them to understand?"
Writing process:
  • Draft the title + one-line description (the hook)
  • Write a concise "What & Why" section (2-4 sentences max)
  • Add a quick-start that gets the reader from zero to working in minimal steps
  • Include real, tested code examples — not pseudocode
  • Add installation instructions appropriate to the ecosystem
  • Only add sections that this specific project needs (see anatomy.md)
  • Present draft to user for review before finalizing
适用于还没有README，或者需要从零开始编写README的项目。
编写前准备：
  • 阅读项目源代码，了解其功能
  • 确定目标受众（是终端用户、开发者，还是两者皆是？）
  • 检查现有文档、配置文件和CI配置，从中梳理项目规范
  • 查看package.json / Cargo.toml / pyproject.toml / go.mod等文件获取项目元数据
  • 询问用户：「这份README的受众是谁，你最想让他们了解的一件事是什么？」
编写流程：
  • 起草标题+一句话描述（吸引读者的钩子）
  • 编写简洁的「是什么&为什么」板块（最多2-4句话）
  • 添加快速入门指南，以最少步骤让读者快速跑通项目
  • 包含真实、经过测试的代码示例——不要用伪代码
  • 添加适配对应技术生态的安装指南
  • 仅添加当前项目实际需要的板块（参考anatomy.md）
  • 定稿前先向用户提交草稿供审核

2. Improve — Existing README

2. 优化模式 — 现有README

For projects with a README that needs enhancement.
Audit first:
  • Read the current README completely
  • Read the project source to check if README is accurate and current
  • Score against the quality checklist
  • Identify gaps, outdated content, and unnecessary sections
  • Present findings to user with specific recommendations
Then improve:
  • Fix factual inaccuracies first (wrong install commands, outdated API examples)
  • Address structural issues (missing sections, poor ordering)
  • Improve clarity and scannability (headers, code blocks, lists)
  • Remove boilerplate that adds no value
  • Verify all code examples work
  • Present changes to user for approval
适用于已有README，但需要优化升级的项目。
先做审核：
  • 完整阅读当前的README
  • 阅读项目源代码，检查README内容是否准确、是否是最新版本
  • 对照质量检查清单打分
  • 找出内容缺口、过时内容和不必要的板块
  • 向用户提交审核结论，并给出具体的优化建议
再做优化：
  • 优先修正内容错误（错误的安装命令、过时的API示例等）
  • 解决结构问题（缺失板块、排序不合理等）
  • 提升内容清晰度和易扫读性（标题、代码块、列表的合理使用）
  • 移除没有价值的模板内容
  • 验证所有代码示例可正常运行
  • 向用户提交修改内容待确认

Key Principles

核心原则

  1. Lead with value — The first 3 lines determine if someone keeps reading
  2. Show, don't tell — Code examples > prose descriptions
  3. Be honest about scope — State what the project does AND what it doesn't do
  4. Respect ecosystem conventions — npm projects look different from Rust crates
  5. Keep it maintained — A README that lies is worse than no README
  6. Link, don't duplicate — Point to docs/ for deep dives, keep the README focused
  7. Test your examples — Broken code examples destroy trust instantly
  1. 价值优先 —— 前3行决定了读者是否会继续阅读
  2. 展示而非叙述 —— 代码示例 > 文字描述
  3. 明确项目边界 —— 既要说明项目能做什么，也要说明不能做什么
  4. 遵循生态规范 —— npm项目的README和Rust crate的README规范不同
  5. 保持内容更新 —— 内容错误的README比没有README更糟糕
  6. 链接而非重复 —— 深度内容指向/docs目录即可，保持README简洁聚焦
  7. 测试示例代码 —— 无法运行的代码示例会立刻摧毁用户的信任

Per-Section Checklist

各板块检查清单

[ ] Title is clear and descriptive (not clever)
[ ] One-liner explains what + why in plain language
[ ] Quick-start gets reader to "it works" in ≤5 steps
[ ] Code examples are real, tested, and copy-pasteable
[ ] Installation covers the project's actual ecosystem
[ ] No orphan sections (every section serves a purpose)
[ ] Badges are useful, not decorative
[ ] License is stated
[ ] Contributing section exists if accepting contributions
[ ] Title is clear and descriptive (not clever)
[ ] One-liner explains what + why in plain language
[ ] Quick-start gets reader to "it works" in ≤5 steps
[ ] Code examples are real, tested, and copy-pasteable
[ ] Installation covers the project's actual ecosystem
[ ] No orphan sections (every section serves a purpose)
[ ] Badges are useful, not decorative
[ ] License is stated
[ ] Contributing section exists if accepting contributions