别让 Git 劝退产品：聊聊小团队落地 Docs-as-Code 时，跨过协同与评审门槛的流程取舍

聊聊 Docs-as-Code 在我们团队落地时踩过的坑。

从研发视角看，Markdown + Git + PR + CI/CD 自动部署确实爽：版本可追溯、跟随代码分支发布，工程化直接拉满。但去年我在一个小团队推这套流程时，没爽多久就卡住了。

最真实的阻力全在协同成本和评审链路上：

1. 非研发根本不想进 Git：让 PM、测试甚至业务方为了改几行参数说明去装 VS Code、学提 PR，一旦遇到冲突直接原地放弃。最后往往变成 PM 在飞书上发一版，研发再人肉搬运到仓库里提 Commit——反而占用了研发排期。
2. Review 体验对文案不友好：研发习惯了在 GitHub / GitLab 上看 Diff 提 Comment，但业务文档的评审需要看上下文渲染效果、需要多段落批注。纯代码平台的评审体验，对非研发来说门槛太高。

我们后来的折中取舍是：不搞原教旨主义。核心的 API 文档、架构设计走 Docs-as-Code，配合 Web-based 编辑器（比如基于 GitLab Web IDE 或 Decap CMS）降低提交门槛；业务需求和协作方案坚决留在在线文档里，上线封版前再跑脚本同步。

大家团队里推 Docs-as-Code 是怎么跨过这道坎的？为了协作体验，你们会给非研发上培训硬推，还是直接做工具妥协采用“混合制”？