Reference guides

参考指南

参考指南是对机械构造, 以及如何操作它的技术性描述.

参考指南只有一项任务: 描述. 参考指南是由代码所决定的, 因为这就是最终参考指南所描述的东西: 关键的类, 函数, API, 因此参考指南应该列出字段, 属性, 方法之类的东西, 并且规定如何使用它们.

参考材料是以信息为导向的

参考材料可以包括说明用法的例子, 但不应该试图解释基本概念, 或如何实现普通任务.

参考材料应该是朴素的, 直奔主题的.

请注意, 这些描述应该包括如何使用这些机器的基本说明 - 例如, 如何实例化一个特定的类, 或者调用某个方法, 或者想函数传递东西时必须采取的预防措施. 然而, 这仅仅是作为技术参考的一部分, 而且需要强调的是, 它不能与怎么做指南相混淆 - 描述软件的正确用法 (技术参考) 与展示如何使用它来达到某种目的 (如何做指南) 是不同的.

对于一些开发者来说, 参考指南是他们能想到的唯一一种文档. 他们已经理解了他们的软件, 他们直到如何使用它. 他们所能想象到的其他人可能需要的, 是关于软件的技术信息.

Reference material tends to be written well. It can even - to some extent - be generated automatically, but this is never sufficient on its own.

参考材料往往写得很好. 它甚至可以 - 在一定程度上 - 自动生成, 但这本身是远远不够的.

和烹饪类比

Wikipedia

试想下一个关于香料的百科文章, 比如说姜.

当你在参考文献中查找生姜时, 你想要要的是关于这味香料的信息: 描述它的来源, 行为, 化学成分, 还有如何烹饪.

你希望无论你查找什么香料, 信息都以类似的方式呈现. 你希望被告知基本事实, 例如生姜和姜黄还有豆蔻是一家子的.

这也是你期望被提醒潜在问题的地方, 例如: 已知生姜会引起某些人的胃部灼热, 或者: 生姜可能会干扰抗凝血剂的作用, 如发华林或阿司匹林.

如何写好的参考指南

围绕代码构建文档

使参考文档和代码有相同的结构, 这样用户就可以同时浏览代码和文档. 这也有助于维护者看到参考文档缺失或需要更新的地方.

要一致

在参考指南中, 结构, 语气, 格式必须都是一致的 - 就像百科全书或字典一样一致.

除了描述, 什么都不做

技术参考做的唯一一件事就是描述, 而且要尽可能清晰和完整. 其他的任何事情 (解释, 讨论, 指示, 猜测, 意见) 不仅仅会分心, 而且也会让它变得难以使用和维护. 只在适当的时候提供示例来说明描述.

Avoid the temptation to use reference material to instruct in how to achieve things, beyond the basic scope of using the software, and don’t allow explanations of concepts or discussions of topics to develop. Instead, link to how-to guides, explanation and introductory tutorials as appropriate.

避免使用参考资料来指导"如何完成某件事情"的这种诱惑, 这超出了使用软件的基本范围, 而且不要解释概念, 也不要讨论开发相关的话题. 取而代之的是, 根据需要链接到怎么做指南, 解释和教程.