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

Scoping and requirements gathering⌗

在公司或项目种，文档需求可能来自各种内部和外部来源，包括以下几种情况

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

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

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

首先，询问stakehoders，他们对内容的预期是什么

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

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

What to document⌗

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

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

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

应该怎么开始，怎么推进呢？ 推荐的是从头开始，然后是结尾，随着时间的推移，基于反馈慢慢填补中间的空白。

这意味着

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

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

Draft⌗

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

在文档上获得多轮反馈可能与你的期望和假设能力直接相关。如果这些在早期阶段不清楚，那么很可能在反馈过程种会显现出来。有时，这是因为你误解或错误地假设了与你沟通的内容。更常见的是，因为人们往往不确定自己的想法，直到看到你具体产出的文档，才直到差异。所以在文档上也需要快速原型，不要在细节上一开始就纠缠太久，细节都可以在后续完善。

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

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

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

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

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

  • 有用的，记下来，未来再安排时间处理，并礼貌地感谢reviewer的comment。
  • 不需要的，以友好，专业的方式推回反馈，并解释不接受的原因。(counter-feedback)
  • 有时候，对特定问题反复纠缠会让人变得烦躁甚至关系变得紧张, 特别是以书面的方式，异步地表达的时候。我们应该都碰到过这种情况：对话和讨论变得紧张、具有攻击性、琐碎。所以交流的语言尽量是包容性的。
  • 不经太多思考，快速写出第一个版本很可能是有很多问题的，但这样做，可能将排接压力、误解、最终还可能节省时间。
  • 在处理在线交流的时候尽可能务实、耐心和开放，才可以保持对话的礼貌和富有成效。

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

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

Feedback⌗

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

公共反馈所见到有用的部分需要筛选

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

Metrics and measuring success⌗

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

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