谈谈文档与工程师

几个场景

• 当一个工程师接触一个新的技术栈, 框架, 组件时。第一件事应该是去官网看文档。可想而知一个好的文档对于一个技术产品是很重要的。

• 当一个工程师入职后, 开始熟悉自己要接手的工作时， 如果有完善的文档能参考， 对于入职新人的体验是很好的。效率也高。

• 日常工作时, 遇到一个问题或流程不清楚， 在文档搜索关键词便能够找到对应文档，体验绝对很好~~

• 在了解一个产品时，想知道某个地方为什么这么设计? 如果产品设计或开发已离职， 但在翻阅产品设计，架构设计文档中找到具体描述 。以及变更说明， 很明显能够加深自己对产品的了解。

• 运维在运维生产环境时, 如果有文档/一些工具能看到每次变更的记录的上下文。 对于运维会减少很大的心智负担。 我们经常会听到 -> 『这个环境没动过啊』

基于上面几个场景能够我们一个信息: 『文档很重要』。我们试图来定义下 文档。 文档本质上前人经验的文档化呈现。本质上是信息， 之前讨论过 信息是用来消除随机不确定性的东西。我们是因为不确定才翻阅文档的。文档因为是前人的经验，能够表达在特定场景下需要做什么？在特定场景下为什么这么做? 那么查看此文档的人就会继承这个经验。针对他遇到的疑惑结合此前的经验来做决策。如果直接能解决问题，那么就提高了效率。 如果没有解决问题，那么也会排除了某些场景， 基于此，也能缩小问题范围， 也是变相的提高了效率。 再进一步，如果最后解决了问题，并更新了文档。那就丰富了知识，做到了知识的迭代更新。这对文档来说至关重要。 时效性。

怎么写文档

基于以上的讨论我们知道 文档的好处 下面聊聊怎么写出好的文档

• 处理问题文档

  在运维工作中经常遇到问题，处理问题的总结基本基于3W1H . 运维工作中一大资产便是故障资产, 基于故障的总结分析形成的知识资产。 这里还有一点时，尽量还原现场, 需要一些截图来丰富。我的经验是想想后面有人来看这个文档，是否有哪些会阻碍其了解来龙去脉。

  • When: 背景
  • What: 现象
  • How: 怎么解决
    • 细节足够 (运维/运营工作中, 这个价值最大)
  • Why: 根因

• 产品设计文档

  当你在负责一个产品(产品可大可小，一个自己开发的小工具也算)时。

  • Why: 为什么做这个 这个能解释清除说明是真的懂
  • How:
    • 通过哪些功能来解决哪些问题 by PM
    • PLAN:
      • 产品规划 by PM
      • 技术实现规划 by 开发
    • 技术架构
      • WHY: 为什么这样选型 by 开发

以上文档应该通过在线文档告知团队成员

以上关于 WHY 的最好通过团队 Review。 通过团队 review 的. 提升文档的权威性

总结

本质上文档是知识集合, 文档与文档的关联形成知识图谱。 领域大牛本质上是这个人领域知识图谱很完善。从工作自身坐起, 积累领域工作经验的好的途径是写好文档。 从程序员的工作来说。代码既领域知识, 好的代码能反应领域知识。公司内部的自研工具平台就是代码的产物。这些东西打通互联组成一张公司的网，让公司职员按照架构好的网来积累公司资产。 好文档，好代码都是公司最好的资产， 是不因人员流失而流失公司的资产。对于管理者来说更应该注重这方面的积累。

后面我想谈谈领域知识与机器。机器根据表达清晰的文档来学习领域知识，来演进为该领域的专家。这是一个令人兴奋的话题。