如何写操作指南（How-to guides）#

Note

操作指南是完全以解决问题（Problem）为导向的材料。

在操作指南中，应当为读者列举出解决现实问题所需的步骤。它们是指引读者完成特定目标的说明书，比如： 如何将 Tensor 的某个维度进行拓展 ， 如何添加一个 Opr 等等。

Warning

当文档中的操作指南远不够完美时，请慎对他人使用 Read The F**king Manual.

软件官方文档中的操作指南象征着绝对的权威性，致力于减少用户使用 Google / Stackoverflow 的频率。这是由于尽管 Google Is Your Friend, 但网络上一份不严谨的指南将让用户对软件的使用产生疑惑。来自初学者视角的一些总结很有可能是错误的，为了避免类似信息导致的蝴蝶效应，操作指南应当做个表率。

与教程的区别#

操作指南和教程是截然不同的两个概念，不要将它们混淆：

教程是由你设计的，仅仅对初学者大有帮助的材料，服务于学习阶段；
操作指南是那些具有一定经验的用户才能提出的问题的答案，服务于使用阶段。

在操作指南中，你可以假设读者已经理解过一些知识背景，并能完成基础的实践。

以做出某道菜为例#

你已经了解了烹饪的基础操作，现在你得到了一份食谱，准备做出里面这道菜。

Note

一份食谱应当有定义明确的结束点，它解决了一个特定的问题，即向某人（可假设已经具备一些基础知识的人）展示了 —— 如何实现某事。

Warning

你不能指望一个从未做过饭的人能遵循食谱上的步骤做出美味佳肴，食谱无法代替烹饪入门课程。与此同时，阅读食谱的人会尝试将已经学会的知识和食谱中的步骤联系起来，如果完全建立不起任何的联系，这只会让读者沮丧，甚至是恼火。
一些软件文档中的操作指南往往写得相当好，指南本身写起来不麻烦，也可以写得很有趣。问题是这种 “好” 仅仅是针对那些有经验的用户而言的，没有教程的话，经验从何而来呢？
在操作指南中过度假设用户已经具备了某种经验，是软件开发人员的傲慢。

如何写出好的操作指南#

提供一系列的步骤#

Note

操作指南必须包含需要按顺序执行的步骤列表。

这一点与教程有些类似，但不必每个步骤都从原点开始讲起，你需要做的是找到合适的起点。操作指南中的步骤应当是可靠的，但不要求保证和教程一样铁一般的可复现性。维护操作指南的频率理论上会远低于教程，除非软件的特性出现了重大改变，导致用法变化。

专注结果，少做解释#

Note

操作指南必须专注于实现实际的目标。

其他任何事情都只会让你的读者分心！就像在教程中一样，详细的解释在这里是不合适的。甚至更极端些 —— 操作指南中不应解释事物，而应专注描述的准确性以及是否能实现目的。它不是那种提供讨论的地方，讨论只会妨碍行动，甚至很多情况下显得多余。如果你认为这些解释确实很重要，请链接到放在别处的它们，让用户根据自己的进度进行阅读判断。

解决特定的问题#

Note

操作指南必须解决特定问题： 我如何…？

这也是操作指南和教程不同的地方：当你在编写操作指南时，可以假设读者知道它们想要实现什么（Want to do what），但不知道如何实现（How to do that）；而在教程中，你有责任决定读者需要探索性地了解哪些内容。

提供一定的灵活性#

Note

操作指南应该允许以稍微不同的方式做同样的事情。

需要保证足够的灵活性，以便用户了解如何在情况稍微有那么一些不同的时候实现目标，或者指引用户将其调整为与你假设的系统或配置稍微略有不同的环境。最典型的例子是 Python 包的安装指南，通常你可以用不同的包管理器安装，或者从源码编译安装。

这些细节不应该过于具体，如果距离我们的目标太遥远，这样的指南将陷入过度解释。

Note

教程需要的是完整的、端到端的指导；而操作指南大可不必。

操作指南可以在作者认为合适的地方开始和结束，也不需要提及所有可能相关的内容。臃肿的操作指南并不能帮助用户快速找到解决方案（甚至很多时候用户仅仅需要的是某一小节的说明而已）。

使用合适的标题#

Note

最常见的做法是以如何（How to）作为开头。

我们需要确保带着解决特定问题需求的用户在访问文档时，能够快速而准确地找到解决方案。让标题和用户脑海中的想法一致，这是最有效率的做法。另外在组织文档的结构时，你需要尽可能地保证层次清晰，让用户在不借助搜索的情况下，能够在尽可能少的跳转次数下找到自己想要的东西。

操作指南作者自查清单#

在发布你的操作指南之前，请尝试回答下面的问题：

我很清楚操作指南所面向的对象，并表明了阅读过哪些教程和解释将有所帮助；
我在操作指南中的描述是准确、具体的，能象征着官方的权威性；
当前的操作指南的的确确能够帮助用户解决特定的某个（某类）问题；
我确保当前操作指南中的起点和终点是合理的，步骤是清晰的；
我在操作指南中没有使用从未出现过的术语和抽象概念，也没有进行多余的解释；
如果我不得不引入一些概念，我确保这些都是链接的形式，相关内容放在了更合适的地方；
我的操作指南所使用的标题是以 “如何” 开头的，在文档中很容易被有需求的用户发现。

通常你的操作指南完成初稿后，需要给一些刚刚经过学习阶段的用户进行试用，收获反馈并及时更新。经验不足的操作指南作者很容易引入一些抽象概念，或者是步骤过于跳跃；而在后期操作指南的维护中，我们更多关注其语句描述是否准确，信息是否与软件版本一致。