如何写参考（Reference）#

Note

参考是完全以提供信息（Information）为导向的材料。

参考指南是对机制和操作方法的 技术性 描述，且只需要负责描述。通常它们的内容是由软件的源代码决定的，用来描述类、函数等 APIs. 因此在参考指南的页面中，应该列出函数、字段、属性、方法等内容，并说明如何使用。这是最基本的要求，但不是全部。

Warning

在搜索引擎中，API 参考是搜索权重最高的页面，好的内容等于进行了搜索引擎优化。

对于一些开发人员来说，参考指南是他们唯一能想到的文档类型。这是因为他们已经相当了解自己的软件，已经知道如何使用它来完成各种各样的任务。因此在他们的脑海中会认为，其他人需要的只是一些技术性的信息，来保证正确地使用。这是一种无意间的傲慢且错误的假设，即将自己的需求当作是用户的实际需求。

一些参考页面可以用工具（比如 Sphinx）完全自动生成，但 “有就行了” 这种程度远远不够。

与操作指南的区别#

参考页面可以包含一定的示例来展示基本用法，但不应试图解释背后的概念或如何实现常见任务。 API 参考中确实包括如何实例化特定类，如何调用特定方法，或在将某些内容传递给函数时必须采取的预防措施。然而这仅仅是其作为技术参考功能的一部分，并不会和操作指南中的内容混淆。

这些参考信息是为了帮助用户理解如何正确地使用 APIs, 而不是如何达到一个特定的目标。

Warning

由于操作不当而产生的信息，属于特定情景下的报错，应该存放在操作指南中作为参考。这些报错信息确实也可以汇总成一个单独的页面，但由于它们都是结合具体使用情景产生的，因此需要索引到对应的操作指南页面。
如果是单个 API 使用不当导致的 Error message, 则应该在对应的 API 参考页面中说明。

假设你已经借助教程和操作指南掌握了很多烹饪知识和技术，现在想查询一下烹饪大全。

Note

当你在大全中查询 姜（Ginger） 这个词，你希望得到的信息应该是：

你希望整本大全都能以类似的方式呈现内容，用来了解相关成分的信息，这些属于基本事实。你也希望能够看到可能导致潜在问题的提示，比如：“已知生姜会引起某些人的胃灼热”，或者是 “生姜可能会干扰抗凝剂的作用，例如华法林或阿司匹林”… 这些提示信息已经足够，而你对于导致这些问题背后的原因和解释并不感兴趣。

Note

为参考文档提供与代码库相同的结构。

这样做可以方便用户同时浏览代码和文档，同时也方便文档的维护人员查看参考文档缺失或者需要更新的地方。

实际上 MegEngine 文档的用户指南和 API 参考页面都是按照源代码结构进行组织的。

Note

在参考指南中，结构、语气、格式都必须一致。

我们需要将参考指南看作是一本字典或百科全书，尽可能做到严谨和风格的统一。

为了让不同的开发者的编码风格保持一致，团队中通常会有一个编程语言的风格指南。对应地，API 参考信息应该也有一个风格指南，类似 Python 文档字符串风格指南。而你现在阅读的这份指南，其目的之一也是为了让 MegEngine 文档的整体结构保持一致，容易编写和维护。

Note

技术参考的唯一职责就是描述，越清晰越完整越好。

任何其它性质的内容（例如解释、讨论、指导、推测、意见）不仅会分散注意力，而且会使它更难使用和维护。但在适当的时候需要提供例子来让描述内容方便理解。这就好像词典中的词语会有自己的词性和使用情景描述，在适当的时候会引入一些例句，例句的难度应当是教程级别的。

Note

这些描述必须全面而准确，并且保证及时更新。

任何实际实现和其描述之间的任何差异都将导致不可避免地导致用户误入歧途。在有必要的情况下，我们有义务提供 API 变化的历史信息，准确地描述其实现的版本，以及功能产生变化的版本（尤其是 Breaking change）。

Warning

对于公共接口等变化，仅仅在 Release Note 或 Changelog 文件中进行说明的做法还不足够；
在 Sphinx 中提供了 versionadded , versionchanged , deprecated 等语法，他们在 API 参考页面中就应该像 note , warning 一样常见，但很少有软件提供这些信息。

在发布你的参考信息之前，请尝试回答下面的问题：

请时刻以编写一本字典的标准去要求自己，让参考指南发挥应有的作用。