Back to Details

crafting-effective-readmes

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Crafting Effective READMEs

编写高效的README文件

Overview

概述

READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder.
Always ask: Who will read this, and what do they need to know?
README用于解答受众会提出的问题。不同的受众需要不同的信息——开源项目的贡献者所需的背景信息，与未来的你打开配置文件夹时所需的信息截然不同。
始终要问： 谁会阅读这份README，他们需要了解什么？

Process

流程

Step 1: Identify the Task

步骤1：明确任务

Ask: "What README task are you working on?"
TaskWhen
CreatingNew project, no README yet
AddingNeed to document something new
UpdatingCapabilities changed, content is stale
ReviewingChecking if README is still accurate
提问：“你正在处理的README任务是什么？”
任务适用场景
创建新项目，尚无README
补充需要记录新内容
更新功能变更，内容已过时
审核检查README是否仍准确

Step 2: Task-Specific Questions

步骤2：任务专属问题

Creating initial README:
  1. What type of project? (see Project Types below)
  2. What problem does this solve in one sentence?
  3. What's the quickest path to "it works"?
  4. Anything notable to highlight?
Adding a section:
  1. What needs documenting?
  2. Where should it go in the existing structure?
  3. Who needs this info most?
Updating existing content:
  1. What changed?
  2. Read current README, identify stale sections
  3. Propose specific edits
Reviewing/refreshing:
  1. Read current README
  2. Check against actual project state (package.json, main files, etc.)
  3. Flag outdated sections
  4. Update "Last reviewed" date if present
创建初始README：
  1. 项目类型是什么？（见下方项目类型）
  2. 它解决了什么问题？用一句话说明
  3. 最快的“可用”路径是什么？
  4. 有什么值得重点强调的内容？
补充章节：
  1. 需要记录什么内容？
  2. 它应该放在现有结构的哪个位置？
  3. 谁最需要这些信息？
更新现有内容：
  1. 发生了什么变更？
  2. 阅读当前README，找出过时的章节
  3. 提出具体的修改建议
审核/更新：
  1. 阅读当前README
  2. 对照实际项目状态（如package.json、主文件等）进行检查
  3. 标记过时章节
  4. 若存在“最后审核日期”，请更新该日期

Step 3: Always Ask

步骤3：必问问题

After drafting, ask: "Anything else to highlight or include that I might have missed?"
草稿完成后，问自己：“有没有什么我可能遗漏的、需要重点强调或补充的内容？”

Project Types

项目类型

TypeAudienceKey SectionsTemplate
Open SourceContributors, users worldwideInstall, Usage, Contributing, License
templates/oss.md
PersonalFuture you, portfolio viewersWhat it does, Tech stack, Learnings
templates/personal.md
InternalTeammates, new hiresSetup, Architecture, Runbooks
templates/internal.md
ConfigFuture you (confused)What's here, Why, How to extend, Gotchas
templates/xdg-config.md
Ask the user if unclear. Don't assume OSS defaults for everything.
类型受众核心章节模板
开源项目全球贡献者、用户安装、使用、贡献指南、许可证
templates/oss.md
个人项目未来的你、作品集浏览者功能介绍、技术栈、经验总结
templates/personal.md
内部项目团队成员、新员工环境搭建、架构说明、运行手册
templates/internal.md
配置文件未来困惑的你内容说明、设计原因、扩展方法、注意事项
templates/xdg-config.md
若不确定，请询问用户。不要默认所有项目都适用开源项目的标准。

Essential Sections (All Types)

必备章节（所有类型）

Every README needs at minimum:
  1. Name - Self-explanatory title
  2. Description - What + why in 1-2 sentences
  3. Usage - How to use it (examples help)
每份README至少需要包含以下内容：
  1. 名称 - 清晰易懂的标题
  2. 描述 - 用1-2句话说明功能与设计初衷
  3. 使用方法 - 如何使用（示例会有帮助）

References

参考资料

  • section-checklist.md
    - Which sections to include by project type
  • style-guide.md
    - Common README mistakes and prose guidance
  • using-references.md
    - Guide to deeper reference materials
  • section-checklist.md
    - 按项目类型划分的章节包含清单
  • style-guide.md
    - 常见README错误与写作指导
  • using-references.md
    - 深度参考资料使用指南