本文目录导读：
这是一个非常经典且实用的问题。Wiki 和 README 的核心区别在于：README 是“入口”和“快速启动”，Wiki 是“图书馆”和“参考手册”。
README 负责回答“这是什么？我该如何快速上手？”；Wiki 负责回答“这个项目的细节、历史、设计决策、贡献流程是什么？”
以下是具体的划分边界和最佳实践：
核心划分原则
| 维度 | README | Wiki |
|---|---|---|
| 目标读者 | 新用户、初次访问者、潜在贡献者 | 现有用户、核心贡献者、维护者、深度使用者 |
| 核心目标 | 快速启动、展示价值、种植线索 | 深度理解、长期保存、协作指南 |
| 信息密度 | 高（精简、关键、直达核心） | 低（详细、全面、分章节） |
| 更新频率 | 高（随版本发布、API变更等更新） | 低（相对稳定，如设计模式、架构说明） |
| 修改权限 | 通常与代码提交绑定（PR 审批） | 更灵活（团队成员可直接编辑） |
明确定义：README 负责什么？
README 是项目的门面,它必须回答以下5个问题：
- 这是什么项目？（一句话介绍 + Logo/截图）
- 它解决了什么问题？（痛点、与其他项目的区别）
- 我如何快速使用它？（安装、简单示例、最低配置）
- 我如何获取帮助？（链接到 Issue、Discord、Stack Overflow）
- 我如何参与贡献？（简要的贡献指南 + 指向 CONTRIBUTING.md 或 Wiki 的链接）
不建议放在 README 中的内容：
- 完整的 API 文档（除非极其简短）。
- 详细的贡献流程（代码规范、提交格式、CI/CD 说明）。
- 历史版本变更日志（CHANGELOG 应独立文件或存在于 Release）。
- 架构设计文档（如 ER 图、UML 图）。
- 常见的故障排除列表（FAQ）。
明确定义：Wiki 负责什么？
Wiki 是项目的知识库，它负责记录所有一次性写清楚就可以长期复用
- 完整的API文档（函数签名、参数说明、返回值、示例）。
- 架构设计文档（系统设计图、数据流、模块依赖、关键技术决策及其理由）。
- 详细安装/配置指南（不同操作系统、不同环境、依赖的第三方服务）。
- 贡献指南（完整的代码规范、PR 流程、测试要求、Code of Conduct）。
- FAQ / 调试指南（常见错误、环境配置问题、性能调优）。
- 版本发布策略（版本号规则、发布流程、回滚策略）。
- 内部约定（命名规范、目录结构说明、数据库迁移策略）。
- 学习资源与相关项目（链接到博客、论文、播客、相关工具）。
不建议放在 Wiki 中的内容：
- 项目的一行介绍（这是 README 的事）。
- 快速开始的代码片段（这是 README 的事）。
- 与当前版本无关、已废弃的历史记录（应归档）。
最佳实践：如何通过链接无缝衔接？
理想的 README 和 Wiki 是相互补充、通过清晰的链接连接起来的，不要在 README 中重复 Wiki 中的详细内容，而是种植线索。
README 中的样式示例：
# MyAwesomeTool 一个用于自动化数据清洗的命令行工具。 🛠️ ## 快速开始 ```bash pip install myawesometool myawesometool --input data.csv --output clean.csv
文档
支持和社区
- 报告Bug： [GitHub Issues]()
- 讨论： [Discord]()
- 查看历史版本： [Releases]()
Wiki 的目录结构示例：
Wiki 首页 (Overview / README)
├── Getting Started (安装、配置、快速上手)
│ ├── Installation
│ ├── Configuration
│ └── Quick Start
├── Guides (操作指南)
│ ├── Data Pipelines
│ ├── Custom Plugins
│ └── Advanced Usage
├── API Reference (API 文档)
│ ├── CLI Commands
│ ├── Python SDK
│ └── REST API
├── Development (开发者指南)
│ ├── Architecture
│ ├── Code Style
│ ├── Testing
│ ├── Release Process
│ └── How to Contribute
└── FAQ & Troubleshooting
├── Common Errors
├── Performance Tips
└── Best Practices特殊情况：项目很小，还需要Wiki吗？
对于只有几百行代码的个人项目，不需要Wiki，把所有必要信息塞进 README 即可，最多再加一个 CONTRIBUTING.md 文件。
判定是否需要 Wiki 的标准：
- README 的长度是否超过了 3-5 屏？
- 是否有超过 10 个以上的 API 或复杂配置项需要解释？
- 是否有多人参与贡献,需要复杂的协作流程？
- 是否有用户反复询问同样的安装或使用问题？
如果以上任何一个问题的答案是“是”，那么你很可能需要 Wiki 来分担 README 的负担。
总结表
| 类型 | 放在哪里？ | 原因 |
|---|---|---|
| 项目简介 & Logo | README | 入口，吸引注意 |
| 快速启动代码 | README | 核心价值，立即体验 |
| 功能截图/演示 | README | 视觉吸引 |
| Badges (CI状态/版本/许可证) | README | 快速传达项目健康度 |
| 安装命令 | README + Wiki | README 放标准安装，Wiki 放所有平台/特殊情况 |
| 完整 API 文档 | Wiki | 太长，会淹没 README |
| 架构图 & 设计决策 | Wiki | 一次性写入，长期参考 |
| 贡献流程 | Wiki (或单独 CONTRIBUTING.md) | 面向核心贡献者，不打扰普通用户 |
| CHANGELOG | 独立文件或 GitHub Release | 专注变更记录，不阻塞 README |
| FAQ | Wiki | 可扩展，不影响 README 简洁性 |
| 许可证 | README (底部) + 单独 LICENSE 文件 | 法律要求，快速告知 |
| 致谢 & 赞助 | README (底部) | 展示社区，表示尊重 |
核心建议： 先写好一个优秀的 README，让它帮你筛选出“我想要更多信息”的用户，然后通过清晰的链接把他们引导到 Wiki 中去，不要把 Wiki 的内容硬塞进 README，也不要把 README 的精简内容复制到 Wiki 里。
