作为内部开发平台的开发者，文档的写作流程和自己写博客也是不同的。

定范围和收集需求#

在公司或项目里，文档需求可能来自各种内部和外部来源，常见的有这几种：

  • 正在进行的新功能，可能来自产品负责人
  • 已经完成的新功能需要文档
  • 由你自己或者其他记录的问题

在开始补充这些文档内容的时候，第一步是要弄清楚当前“完成”的定义。不同人对其有不同的看法。尽管你可能已经尽力而为了，你仍然可能发现你对“完成”的理解和实际情况不符。

根据你合作的人和你所在的公司或项目类型，你可能需要采取不同的措施来减少这种情况的发生。

我的做法是先问 stakeholders 对内容的预期是什么

  • 产品负责人可能希望你描述新功能如何帮助用户解决问题。
  • 一位工程师可能希望你描述功能的具体细节，比如组件是否有本地缓存，是否支持动态变更，QPS 能达到多少。

需要站在 stakeholders 的角度，了解他们的意图，很多时候并不是简单的事情。

写哪些文档#

任何工作开始之前都有个工作量评估，你可能会想要知道要做什么以及需要多少文档。

文档是个迭代的过程，尤其是当你是一个小团队（没有足够人力和时间）或者作为另一项工作的一部分来完成文档的时候。

  • 几乎不可能一次性记录下产品可能需要的所有内容。（我不知道有没有人能在项目过程中记录下所有细节并在最后的文档中体现，但我知道这些都需要时间。）
  • 除非你在的某些行业，要求在发布时必须有完整且准确的文档，例如医疗、敏感工业等，否则不太可能需要一次性记录所有内容。

应该怎么开始，怎么推进呢？ 我见到比较可行的顺序是：先写开头，再写结尾，中间的空白随着反馈慢慢填。

这意味着

  • 先出一两篇 getting started guide，再补上能覆盖 API 或 SDK 函数的 reference documentation。
  • 当都准备好后，你就可以发布"minimum viable documentation"。
    • 这些 getting started guides 对想体验产品的人来说要足够可以衡量是否满足他们的需求。
    • reference doc 要足够让知道自己要做什么的人获得要使用的组件的足够细节。

在这些内容到位后，你可以利用 product roadmap，在后续排期中，进一步完善文档。

初稿与评审反馈#

与其他任何形式的写作类似，一稿往往是不够的。一旦你有了初稿，你需要让所有相关的 stakeholders 查看并给出意见。 这个过程可能需要一些时间，但对准确性要求高的项目来说，这笔成本大概省不掉。

要走几轮反馈，很大程度取决于一开始把预期和假设讲得有多清楚。这些东西早期没说清，到反馈阶段基本都会冒出来。有时是我自己误解了对方的意思，或者把某个假设当成了共识；更常见的情况是，对方在看到具体文档之前自己也说不清想要什么，看到了才发现和预期有差。所以文档也需要快速原型，一开始别在细节上纠缠太久，细节可以后面补。

文档反馈通常有两种极端：

  • 几乎没有反馈，以至于你不确定任何人的想法
  • 或者有太多反馈，你不知道从哪里开始。

如果你没有收到足够反馈，你可能需要安排特定的会议从 stakeholders 那里获得反馈。当面对大量的文本或修改列表时，人们可能有些无所适从，所以你需要问具体的问题。

太多的反馈并不一定意味着你做得不好。有些 reviewer 很有主见，或者有许多想法要分享。

处理太多反馈的困难在于筛选出有用的部分，并决定怎么处理：

  • 有用的，记下来，未来再安排时间处理，并礼貌地感谢 reviewer 的 comment。
  • 不需要的，以友好、专业的方式把反馈推回去，并解释不接受的原因（counter-feedback）。
  • 有时候，对特定问题反复纠缠会让人变得烦躁甚至关系紧张，特别是以书面、异步的方式表达的时候。我们应该都碰到过这种情况：对话和讨论变得紧张、具有攻击性、琐碎。所以交流的语言尽量是包容性的。
  • 不多想就先写出第一版，内容大概会有不少问题，但这样能更早暴露排期压力和理解偏差，整体反而更省时间。
  • 在处理在线交流的时候尽可能务实、耐心和开放，才可以保持对话的礼貌和富有成效。

那么，什么时候反馈可以完成，并发布文档更改呢？

大多数项目可以在后续过程中不断迭代。通常在外部压力下，会设定一个发布时间，在期限内需要结束反馈并发布。

用户反馈#

用户可以通过 gitlab/github issue 提出 feedback。当然有些团队也通过调查问卷的方式进行。

公共反馈里有用的部分也需要筛选：

  • 某些虽然有效，但影响人数太少，可能不值得处理
  • 有些人认为的问题，可能实际上并不是问题，而是因为背景知识的缺失或其他原因造成的。
  • 内部路线图、优先事项和预定排期可能会优于外部反馈和请求。但这并不意味着你可以忽略外部输入，可能还是需要和反馈者沟通。

用指标衡量效果#

我们有收集一些 metrics 来评估文档的效果。比如收集文档页面的访问量，停留时间等。追踪用户是如何浏览页面的，可以知道哪些文档需要重点维护，哪些使用率很低，是否需要提高。

在内部的 Mattermost channel 反馈的问题，大部分都需要能够在文档中找到答案，我们会给用户发送相关链接，让用户自助处理。如果文档无法满足，我们需要人工对接。人工介入排查问题和答复也会纳入文档的参考指标。减少人工答疑的成本也是文档站的目的之一。