“完成优于完美”不仅仅是一句口号，更像是Datadog技术作者的座右铭。毕竟，谁不想在“完美”的文档上留下自己的痕迹呢？😉
前两年 PLG(产品驱动增长)概念火热的时候，IT 运维领域有一家 PLG 代表性厂商，就是 Datadog。要实现 PLG，很重要的一点就是文档知识库足以支撑用户自服务。Datadog 的技术文档团队，无疑是 PLG 领域一个值得深入研究的案例。前段时间，我碰巧看到 writethedocs.org 官网，发现其实 Datadog 的技术文档团队负责人做过公开分享，太棒了！这篇文章，我就来总结一下她的分享内容，看看 Datadog 是如何在技术文档写作领域中保持高效和创新的。
一、团队概况
Datadog 的技术文档写作团队由12名成员组成，他们分布在美国各地，大多远程工作，部分在 Datadog 办公室。作为对比，Datadog 公司产研部门拥有超过2000名 IT 工程师与产品经理。当然也不是所有这些人的工作都跟技术文档直接相关。
根据分享内的说法，美国传统观点认为，每10到15名工程师配备1名技术作者才是合理的，但根据美国劳工统计局的数据，实际上软件工程师与技术作者的比例为30:1。
当然，我们前面已经看到了 Datadog 的工程师和技术作者的比例是 2000/12，大概是 166:1。这个比例比行业平均配置还要低五倍！
所以 Datadog 技术文档团队必须要通过一些灵活的手段，来应对这种不平衡的配比。包括和产研的紧密合作，充分发挥开源社区和内部一线技术同事的协作反馈等。
二、招聘与人才培养策略
我们都知道，IT 领域，高素质人才是第一生产力。我之前也尝试看过一些国内的技术文档写作社区的情况，发现国内社区人才大多是外语专业的“传播学”出身，工作职责也集中在跨国企业的原版文档翻译。对想要构建原厂技术文档团队的国内企业来说，人才招聘和培养都很难。
事实上，Datadog 也招不到！分享中提到，Datadog 技术写作团队主要是通过他们的“嵌入”计划，实现公司内部活水的招聘扩张。
具体的说，”嵌入“计划可以让 Datadog 现有的 IT 技术支持工程师，transfer 到技术写作团队，临时性的工作三个星期。三个星期后双向选择是留下，还是回原团队。这样体验实际工作内容的方式，更有效地吸引有产品和技术知识、并且正在寻求转岗的一线技术员工加入文档团队。
这个策略，成功地帮助 Datadog 技术写作团队，从公司内部招募到了不少具备深厚产品技术知识、并热衷于高效产出的“中阶”职业作者。同时，这些老同事，一般也会携带自己过去几年积累的产品技术知识，加速文档的产出。
三、工作标准和团队文化
在团队文化上，Datadog 强调“完成优于完美”的理念，鼓励快速迭代文档而不是追求写出完美的第一版。所有人，包括产研和客户，都应该接受文档存在错误、难以查找和缺失信息的现状，而技术文档团队，则在此前提之下，集中精力来一个接着一个地解决问题，而不是掩耳盗铃。
技术写作团队解决问题的方式，是建立一个指导性的标准，帮助外部协作者顺畅地提交文档，而不是阻碍大家的协作。所以，她们非常重视作者和协作者之间的关系，特别是和产品经理、经常使用文档的技术支持工程师、以及GitHub 上偶尔贡献文档的随机贡献者之间的关系。
此外，Datadog 会定期举行 hackathon 活动。hackathon 不光是针对研发的，也鼓励技术作者投入时间到一些实验性项目、维护任务或单纯就是个人兴趣的项目上，增强团队的技术敏感度和活力。这些项目没有限制，没有约束，你可以是帮别人更新一个陈年老文档，也可以是跟 Datadog 一毛钱关系都没有的事情。
四、具体工作细节
分享中还提到了一些 Datadog 技术文档团队的工作细节。这里也摘录一下：
- 文档标准，不只是文档编写和发布的标准，也包括质量标准。Datadog 本次分享中并没有明确谈质量标准的细节。不过writethedocs.org 大会上有其他相关分享，我也放到这里来：通过 github 的 pre-commit hook，对文档质量进行评分，包括Flesch Reading Ease、Gunning fog、Automated Readability Index、Dale Chall Readability Score、Coleman Liau Index五种分值进行加权计算。变更后分值如果下降，这个提交直接拒掉。这几个可阅读性测试的计算公式在 Wikipedia 上都可以直接查看。可惜的是，它们都是针对英文文本研究设计的。中文在可阅读性量化评估方面，几乎是空白！
- 技术作者要负责教育产品经理如何直接在Pull Request中提供文档更新。
- 实行“按需分配”的 On-Call 制度，每天一个值班的技术作者，除了客服响应以外，还要负责审查 Datadog 研发在当天提交的所有 Pull Request 代码，包括合并、搁置、转交他人审查或关闭——当然他们只从文档角度看代码，不涉及业务逻辑和技术原理评审——这样，他们 oncall 的时候才能有效应对来自售后和客户和研发的，针对全公司任意文档的修复意见。要知道 datadog 现在应该有 35+ 个 SaaS 产品，对应的 github 文档仓库里有 5000+ 个 markdown 文档，4000+ 个文档配图。如果没有这个独特的 oncall 机制，很难想象他们如何保证文档能真实反应产品现状！不知道 LLM 现在会在这方面有什么改进么～
其他
Datadog 技术写作团队通过一系列创新的策略方法，成功地应对了，SaaS 产品快速迭代下，技术文档写作的挑战，确保了Datadog 技术文档能有效地支撑用户自服务。尤其是其中技术作者 oncall、审查代码、从技术支持工程师转岗、文档质量量化评审等具体措施，也非常值得国内软件公司学习和借鉴。
此外，writethedocs.org 大会上还有很多其他玩法，比如如何通过自动化测试更新文档配图等等，大家也可以一看。
btw，几年前我曾经通过问卷调查的方式，量化过日志易技术文档的用户满意度，以及随版本迭代的升降情况。后续可能也会尝试用 LLM 来量化日志易技术文档的可阅读性指标。敬请期待。
参考资料
- Write the Docs Conferences
- Kari Halsted - GREAT BIG ENGINEERING ORG; itty bitty docs team
- Lexi playground
- How we automatically keep our Documentation Screenshots up to date
