README 心理学与 Readme Driven Development — 原始数据

用户心理与第一印象

注意力时间窗数据

• 3 秒: 访客第一次看到 profile/portfolio 时形成评价的时间
• 7 秒: 人类平均注意力窗口（2025 年研究）
• 一个 GIF 或图片可以在内容不够吸引人时留住访客
• 项目有完善 README 的获得 3x 更多 star 和 5x 更多贡献

决策心理学

• README 是”数字简历”和”项目名片”
• 是用户、贡献者、雇主对项目的第一印象
• “一份精心设计的 README 可以决定一个项目是被注意还是被忽视”

信息缺失问题

• 学术研究发现：大多数 README 解释了 “What” 和 “How”
• 但缺少 “Why”（项目目的和当前状态）
• 缺失 “Why” = 用户无法做出使用/贡献的决策
• 这是 README 设计中最常见也最严重的心理学失误

信任建立要素

• 徽章（build passing, coverage %）= 质量信号
• 贡献者列表 = 社区健康信号
• 许可证 = 法律安全信号
• 最后更新日期 = 活跃度信号
• Star/Fork 数量 = 社会认同信号

认知负荷管理

• 大块文本 → 高认知负荷 → 用户离开
• 项目符号、编号列表、表格 → 降低认知负荷
• 可扫描的标题层级 → 允许选择性深入
• 目录（TOC）→ 给用户控制感

Readme Driven Development（RDD）

来源: Tom Preston-Werner（GitHub 联合创始人，2010 年）

URL: https://tom.preston-werner.com/2010/08/23/readme-driven-development

核心论点

“Until you’ve written about your software, you have no idea what you’ll be coding.”

两个极端问题：

1. 完美执行错误的规范 → 毫无价值
2. 精美的库没有文档 → 几乎毫无价值

RDD 方法论

在编写任何代码之前，先写 README：

1. 标题和副标题
2. 一段话解释代码意图和要解决的问题
3. Getting Started 信息

四大优势

1. 思维清晰化 — 写之前被迫深度思考设计
2. 文档完整性 — 项目初期写文档动力最足（热情期）
3. 团队协作 — 明确的接口定义让团队并行开发
4. 可论证性 — “It’s a lot simpler to have a discussion based on something written down”

RDD vs DDD（文档驱动开发）

• RDD 是 DDD 的子集/精简版
• 限制在单一文件（README）内 → 避免 DDD 退化为瀑布模式
• README 是”最小可行文档”

适用范围

• 适合: scope 清晰有限的包/库/工具开发
• 不适合: 大型业务应用（会变成瀑布模式）

其他 RDD 来源补充

Pony Foo: README 是”codebase 中最重要的文档” Ben Christel: 写 README 的过程是”真正的创造行为” Rathes.me: 强调 RDD 如何帮助模块化设计 — 如果 README 太复杂，说明模块拆分不够

readme.so 模板工具分析

URL: https://readme.so/editor

工具设计理念

• “The easiest way to create a README”
• 左侧面板选择 section → 中间编辑 → 右侧预览
• 支持拖拽排序和自定义 section

完整可用 Section 列表（34 个）

项目信息类:

• Title and Description
• Logo
• Badges
• Screenshots
• Demo
• Features
• Tech（技术栈）

使用指南类:

• Installation
• Run Locally
• Deployment
• Environment Variables
• Usage/Examples
• API Reference
• Running Tests

文档扩展类:

• Documentation
• FAQ
• Appendix
• Lessons
• Optimizations
• Color Reference

社区与归属类:

• Contributing
• Authors
• Acknowledgements
• License
• Support
• Feedback
• Related
• Roadmap
• Used By

GitHub Profile 专用:

• About Me
• Introduction
• Links
• Other
• Skills

暗含的信息架构

readme.so 的 section 列表反映了社区对”好 README 应包含什么”的共识。高频使用的 section（Title、Installation、Usage、Features、License）构成了 README 的最小必需集。

模板工具的结构对比

Best-README-Template (othneildrew, 39k+ stars)

Header → About → Built With → Getting Started → Prerequisites →
Installation → Usage → Roadmap → Contributing → License →
Contact → Acknowledgments

makeareadme.com

Name → Description → Badges → Visuals → Install → Usage →
Support → Roadmap → Contributing → Authors → License → Status

FreeCodeCamp 推荐

项目简介 → 功能特性 → 技术栈 → 快速开始 → 仓库结构 →
架构概览 → API文档 → 环境变量 → 测试 → CI/CD →
版本管理 → 贡献指南 → 许可证

共同的信息顺序模式

所有模板都遵循相同的心理模型：

是什么（What）→ 为什么用（Why）→ 怎么开始（How to Start）
→ 怎么用（How to Use）→ 怎么参与（How to Contribute）
→ 法律/归属（Legal/Credits）