文章建议将文档与代码存放在同一代码仓库中，利用版本控制保持同步，便于搜索更新，支持文档驱动开发，并可通过工具自动生成API文档，提高效率。

将文档移入代码仓库的五大理由

（开篇引用中国谚语"好记性不如烂笔头"点明文档重要性）

核心观点： 1. 版本控制优势 - 文档与代码同步演进 - 利用现有Git系统处理多人协作冲突 - 避免使用独立版本控制系统

2. 代码文档一体化

• 支持代码搜索工具同时检索文档
• 实现文档驱动开发（DDD）理念
• 自动生成API文档（Sphinx/JSDoc等工具）

3. 质量保障机制

• 文档中的代码示例可纳入CI测试（如Python的doctest）
• 文档即规范（Documentation as spec）

4. AI时代新机遇

• AI代理可自动维护文档时效性
• 减少人工同步代码与文档的工作量
• 高阶上下文（RFC/PRD等）提升AI理解力

5. 知识沉淀价值

• 将研究结论转化为"元方案"文档
• 结构化日志等经验可团队复用
• 节省后续开发者的调研成本

常见质疑回应： - 版本控制优于外部文档系统 - 文档评审不应成为更新阻碍 - AI生成文档需人工审核优化 - 非技术成员可通过内部网站访问 - 协作工具（如Google Docs）可导出Markdown

行业趋势： - 工程师向左移位（Shift Left） - 规范文件逐渐成为核心资产 - 非技术人员代码访问权限增加

（文末列出7个专业参考资料，涵盖文档驱动开发、自动化测试等主题）

评论总结：

1. 反对以AI为由改变开发实践

   • 认为AI不应成为改变开发社区管理方式的原因
   • "because of AI is not a valid reason to change anything" (jaredcwhite)
   • "这些实践在LLM出现前就是最佳实践" (susam)

2. 支持文档与代码同仓的长期价值

   • 可确保文档与代码同步，避免脱节
   • "pull requests can't land without updating docs" (redgridtactical)
   • "out-of-band docs是长期痛点" (petcat)

3. AI工具的实际应用案例

   • 展示AI如何自动更新文档和检测不一致
   • "Claude自动添加API参数并更新文档" (themanmaran)
   • "AI提高了文档编写积极性" (gbro3n)

4. 对纯Markdown方案的质疑

   • 指出协作场景下的功能局限性
   • "MD在评论/标签/历史追踪方面不如Confluence" (xixixao)
   • "需要持续同步代码状态" (alansaber)

5. 文档管理方式的创新建议

   • 提出混合解决方案和工具改进
   • "建议构建双向同步工具" (r2vcap)
   • "开发更好的文档审阅工具" (cborenstein)

6. 开发者态度的反讽观察

   • 批评开发者因AI才重视文档的讽刺现象
   • "开发者需要AI替身才意识到文档价值" (theletterf)
   • "人类协作者本应更早获得这些考虑" (susam)

关键分歧：
- 支持派强调版本控制与自动化优势（9/13/17）
- 反对派担忧协作效率和信息安全（2/7/15）

趋势：AI工具正在强化（而非颠覆）文档管理的最佳实践。