如何写解释(Explanation)

注解

解释是完全以理解(Understanding)为导向的材料。

它阐明了一个特定的主题,拓宽了文档的边界。

解释可以被理解成讨论,它们本质上是散漫自由的:

  • 读者可以选择借助简单的部分放松一下,也可以选择在深层次的部分中探索细节;

  • 通过解释,作者能够帮助读者从更高的层面或者不同的视角去理解已有的信息;

  • 用户在闲暇的时候可能更愿意阅读一些解释性的内容,而不是阅读代码。

何时需要解释?

注解

  • 解释型的文档很少被明确地创建出来,而往往是分散在其它三个类型的文档中。

  • 在 MegEngine 的开发者指南中,专门留有 MegEngine 增强提案(MEPs) 用于提供关于 MegEngine 开发相关的一切解释, 它本质上是对解释和讨论信息的总结。

通常你会在文档页面中看到名为 “背景”、“注解”、“关键” 等字样来表明这儿有一段解释(讨论),或得到一段总结。 但这种情况也不是绝对的,很多时候话语本身就具备有解释的属性,只是不会被刻意强调。

你也可以利用独立的页面来对某个主题展开解释,但主题的内容应该和教程、操作指南、参考信息都不同。 另外,当你想要针对某个问题进行讨论时,要在文档中找到合适的地方来存放这些信息。

其它类型的解释信息通常出现在教程或操作指南的开头,作为背景信息。

对于那些不希望强制所有用户阅读,但又希望被特定用户关注到的信息,可以适当使用折叠样式或超链接。

以了解烹饪历史为例

想一想在历史、科学和技术的背景下去讨论与烹饪有关的话题,比如解释八大菜系中粤菜的历史。

它不会教你如何做出某道特定的菜,也不会描述一些食材的信息。 相反,它将从多个角度分析和考虑事物,可能描述了我们为什么要这样做,替代方案有哪些, 甚至可能将比较糟糕的做法也进行了讨论。

这样的解释能够丰富我们对已有知识的理解,即使它无法帮助我们进行新的实际应用。 可能阅读过一些解释信息后,你在进行某项工作时能够更加条理清晰。让你胸有成竹,这才是解释的价值。

如何写出好的解释

提供上下文

注解

解释是提供背景和上下文的地方。

例如 MegEngine 中 Tensor 的 Stride 机制Autodiff 的实现原理

解释并不是凭空产生的,它一定是用来解答我们脑海中的特定的疑惑,而其它类型的文档做不到这一点。

它们还可以告知读者我们当前为什么要这样做 —— 设计决策、历史原因、技术限制等等。

讨论替代方案和意见

注解

解释可以讨论替代方案,或者针对同一种问题的多种解法。

我们甚至可以讨论一些相反的意见,并解释出于什么样的原因这个方案没有被采纳,或这个功能不被支持。

专注于补充说明

注解

一份单独的解释性的文档,应该专注于对某个主题进行拓展补充。

文档的这些功能已经在其他部分进行了处理,在解释材料中应该做点不一样的事情。