如何写解释（Explanation）#

Note

解释是完全以理解（Understanding）为导向的材料。

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

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

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

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

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

何时需要解释？#

Note

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

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

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

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

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

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

以了解烹饪历史为例#

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

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

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

如何写出好的解释#

提供上下文#

Note

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

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

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

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

讨论替代方案和意见#

Note

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

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

专注于补充说明#

Note

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

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