类型：代码托管平台
简介：只支持Git作为唯一的版本库格式进行托管，故名GitHub。
GitHub仓库可以用README、docs目录、GitHub Pages和Wiki承载文档。很多团队不知道该把资料放在哪里，最后README、Wiki和聊天记录各存一份，内容很快不一致。下面按GitHub实际功能，讲一套判断和配置方法。
第一步：先判断文档和代码的关系
如果文档会随着代码一起变化，例如安装说明、API参数、配置文件、部署步骤，优先放在仓库docs目录或README中。这样可以通过Pull Request和代码一起审查。
如果文档是经验沉淀，例如会议记录、故障复盘、历史决策、临时方案，可以放在Wiki。Wiki更适合快速记录，但不适合替代正式版本文档。
第二步：启用或检查Wiki功能
进入仓库Settings，在General页面找到Features，确认Wikis已勾选。启用后，仓库顶部会出现Wiki入口。点击Create the first page即可创建首页。
Wiki首页建议不要写成长文，而应作为目录。可以分成：项目背景、部署记录、故障复盘、历史决策、常见问题。每个页面标题要清楚，避免出现“记录1”“临时文档”这类无法搜索的名字。
第三步：建立仓库文档目录
正式文档可以放在docs目录。例如：
docs/ getting-started.md configuration.md deployment.md troubleshooting.md
README里只保留快速开始和入口链接，不要把所有内容都塞进首页。这样README负责引导，docs负责详细说明，Wiki负责经验记录。
第四步：给文档加适用版本
无论放在docs还是Wiki，重要页面都建议写明适用版本或更新时间。例如：
- 适用版本：v2.x
- 最后更新：2026-06-17
- 维护人：项目维护组
这能降低误用旧文档的风险。尤其是部署步骤和配置参数，过时后很容易导致实际操作失败。
第五步：用PR维护正式文档
当代码改动影响安装、配置或部署时，应要求PR同时更新docs。可以在PR模板里加入：
- [ ] 本次改动是否需要更新文档 - [ ] 如需要，已更新README或docs目录
这样正式文档会跟随代码变化，不会被遗忘。对外发布的文档，最好走PR审查，而不是随手改Wiki。
第六步：用Wiki沉淀故障和决策
线上故障、方案取舍、会议结论可以先写Wiki。故障复盘页面建议包含时间、影响范围、原因、处理过程、后续改进。历史决策页面建议写清背景、备选方案、选择理由和后续影响。
这些内容不一定适合放进README，但对新成员理解项目很有帮助。Wiki的价值在于保存上下文，而不是替代正式文档。
第七步：避免两边内容重复
同一份安装教程不要同时放在README、docs和Wiki里。可以在Wiki里放链接，指向docs里的正式教程；也可以在docs里引用Wiki中的故障复盘。重复内容越多，越容易出现一个地方更新、另一个地方过时。
如果发现重复页面，应保留一个主版本，其余页面改成跳转说明或归档。知识库要可维护，首先要减少重复。
第八步：每月做一次文档巡检
文档巡检可以检查四件事：README入口是否有效，docs里的命令是否还能运行，Wiki页面是否有过时内容，重要页面是否缺少更新时间。巡检不需要很重，但要持续。
GitHub Wiki和仓库文档不是二选一。正式、可审查、随代码变化的内容放docs；经验、复盘、历史决策放Wiki。边界清楚后，团队知识才不会越积越乱。
