README 结构与信息架构 - 原始数据

来源 1: FreeCodeCamp - How to Structure Your README File

文章链接

标准 README 结构（推荐顺序）

1. 项目标题与描述 - 做什么？给谁用？保持简短。
2. Demo（可选） - GIF、图片、或在线演示链接。视觉抓注意力。
3. 安装 - 分步说明。
4. 使用 - 如何运行或使用，包含命令示例或截图。
5. 功能 - 列出关键功能让用户知道期望什么。
6. 技术栈 - 使用的语言、框架和工具。
7. 贡献 - 如果欢迎协作，包含指南。
8. 许可证 - 让人知道如何使用或复用代码。
9. 致谢（可选） - 感谢帮助或启发的人。

关键原则

• “每个项目都不同，考虑哪些部分适用于你的项目”
• 模板中的部分是大多数开源项目的建议

来源 2: makeareadme.com

网站

推荐章节结构

核心建议

• “too long is better than too short” —— 优先完整性
• 使用 README.md 作为文件名（传统大写格式）
• 考虑创建专门的 CONTRIBUTING.md 文件
• 配合维基、文档网站（MkDocs、Docusaurus）和 changelog 使用

来源 3: othneildrew/Best-README-Template

GitHub 仓库

模板章节流

1. Header 元素 - Badges（contributors, forks, stars, issues, license, social links）
2. 标题与钩子 - 项目名 + tagline + CTA 按钮
3. 目录 (ToC) - 可折叠导航
4. About The Project (含 “Built With” 子部分)
5. Getting Started (Prerequisites → Installation)
6. Usage
7. Roadmap
8. Contributing (含贡献者可视化)
9. License
10. Contact
11. Acknowledgments

设计原则

• 渐进式披露: 通过复制粘贴自定义
• 用户中心框架: “Your time should be focused on creating something amazing”
• 视觉增强: Badge shields 和贡献者图像传达项目健康指标
• 可访问性: 锚点链接和返回顶部导航便于浏览
• 模块化: 每个部分独立，可选择性采用或重排序

来源 4: Google README 风格指南

Google Style Guide

核心要求

文件命名: 必须命名为 README.md（区分大小写）

位置: 放在代码库顶层目录，不要放在文档目录内

强制内容:

1. 包/库描述 - 包含什么及其预期用途
2. 联系信息 - 项目联系人
3. 状态声明 - 是否弃用或限制发布
4. 使用说明 - 包含示例代码和可复制的构建命令
5. 文档链接 - 相关支持文档引用

规模原则: 每个顶层包目录都应有最新的 README.md 文件，尤其是为其他团队提供接口的目录

来源 5: README.md 信息架构心理学

综合 UX 心理学资源

适用于 README 的 UX 原则

Hick’s Law（希克定律）

• 选择越多，决策时间越长
• 在 README 中: 不要立刻提供所有导航选项，先给广泛类别再分解为子类别
• 应用: 使用分层标题和折叠部分管理选项

Cognitive Load（认知负荷）

• 同时呈现太多信息让人不堪重负
• 在 README 中: 渐进式披露是关键
• 应用: 快速开始 → 详细指南 → API 参考的梯度

Gestalt Principles（格式塔原则）

• 接近性: 相关内容放在一起
• 相似性: 相同类型的内容使用一致的格式
• 闭合性: 大脑自动补全缺失信息
• 应用: badges 分组、代码块的一致性、章节的视觉分隔

渐进式披露 (Progressive Disclosure)

• 这是所有优秀 README 的共同模式
• 先展示核心信息，让用户选择深入
• 实现方式: 折叠部分、“查看更多” 链接、外链到完整文档