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?"

Task	When
Creating	New project, no README yet
Adding	Need to document something new
Updating	Capabilities changed, content is stale
Reviewing	Checking if README is still accurate

提问：“你正在处理的README任务是什么？”

任务	适用场景
创建	新项目，尚无README
补充	需要记录新内容
更新	功能变更，内容已过时
审核	检查README是否仍准确

Step 2: Task-Specific Questions

步骤2：任务专属问题

Creating initial README:

What type of project? (see Project Types below)
What problem does this solve in one sentence?
What's the quickest path to "it works"?
Anything notable to highlight?

Adding a section:

What needs documenting?
Where should it go in the existing structure?
Who needs this info most?

Updating existing content:

What changed?
Read current README, identify stale sections
Propose specific edits

Reviewing/refreshing:

Read current README
Check against actual project state (package.json, main files, etc.)
Flag outdated sections
Update "Last reviewed" date if present

创建初始README：

项目类型是什么？（见下方项目类型）
它解决了什么问题？用一句话说明
最快的“可用”路径是什么？
有什么值得重点强调的内容？

补充章节：

需要记录什么内容？
它应该放在现有结构的哪个位置？
谁最需要这些信息？

更新现有内容：

发生了什么变更？
阅读当前README，找出过时的章节
提出具体的修改建议

审核/更新：

阅读当前README
对照实际项目状态（如package.json、主文件等）进行检查
标记过时章节
若存在“最后审核日期”，请更新该日期

Step 3: Always Ask

步骤3：必问问题

After drafting, ask: "Anything else to highlight or include that I might have missed?"

草稿完成后，问自己：“有没有什么我可能遗漏的、需要重点强调或补充的内容？”

Project Types

项目类型

Type	Audience	Key Sections	Template
Open Source	Contributors, users worldwide	Install, Usage, Contributing, License	`templates/oss.md`
Personal	Future you, portfolio viewers	What it does, Tech stack, Learnings	`templates/personal.md`
Internal	Teammates, new hires	Setup, Architecture, Runbooks	`templates/internal.md`
Config	Future 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:

Name - Self-explanatory title
Description - What + why in 1-2 sentences
Usage - How to use it (examples help)

每份README至少需要包含以下内容：

名称 - 清晰易懂的标题
描述 - 用1-2句话说明功能与设计初衷
使用方法 - 如何使用（示例会有帮助）

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
```
- 深度参考资料使用指南