How-to guides

怎么做指南

怎么做指南带领读者完成解决实际问题所需的步骤.

它们是食谱, 知道如何实现一个特定的目标 - 例如: 如何创建一个 web 表单; 如何绘制一个三维数据集; 如何启用 LDAP 身份验证.

他们完全是 目标导向的.

怎么做指南完全不同于教程, 并且不应该将他们混淆:

教程是你认为初学者需要知道的东西.

怎么做指南是一个回答, 只有有一些经验的用户才能提出这个问题.

在怎么做指南里, 你可以假设用户有一些知识和理解. 你可以假设用户已经知道如何做一些基本的事情和使用一些基本的工具.

不像教程, 软件文档中的怎么做指南往往做得很好. 他们也很有趣, 很容易写.

一份食谱

想想用来准备食物的食谱.

一份菜谱有一个明确的目的. 它解决一个特定的问题. 它向一个人展示如何实现某些东西 - 他可以假设他已经有一些基本的知识.

不能指望一个从来没有做过饭的人能够按照食谱成功地做饭, 所以食谱不能代替烹饪课. 同时, 阅读食谱的人如果发现食谱试图教他们已经知道的基础知识, 或者包含了与食材无关的讨论, 他们会感到恼怒.

怎么做指南必须包含一个步骤清单, 需要按顺序进行(就像教程一样). 你不必从最开始的地方开始, 只需在一个合理的起点上. 怎么做指南应该是可靠的, 但它们不需要像教程那样具有那么强的可重复性.

怎么做指南必须专注于实现一个实际的目标. 其他的东西都会分散注意力. 就像在教程中一样, 详细的解释在这里是不合适的.

怎么做指南必须解决一个具体的问题: 我怎样才能......?

这是怎么做指南区别于教程的一种方式: 当涉及到怎么做指南时, 可以假设读者知道他们应该实现什么, 但还不知道如何实现 - 而在教程中, 你负责决定读者需要了解哪些事情.

怎么做指南不应该解释事情. 它不是讨论这类问题的地方, 它们只会妨碍行动的进行. 如果解释是重要的, 就链接到它们.

怎么做指南应该允许用不同的方式来做同样的事情. 它需要有足够的灵活性, 使用户能够看到它将如何适用于与你所描述的略有不同的例子, 或者理解如何使它适应与你所假设的略有不同的系统或配置. 不要太具体, 以至于除了你所考虑的确切目的外, 怎么做指南对任何事情都没有用处.

实用性比完整性更有价值. 教程需要是完整的, 端到端的指南, 而怎么做指南则不然. 它们可以在你认为合适的地方开始和结束. 他们也不需要提及所有可以提及的东西, 只是因为它与主题有关. 一个臃肿的指南并不能帮助用户快速地找到他们的解决方案.

一个指南文档的标题应该准确地告诉用户它做了什么. "如何创建一个基于类的视图"是一个好的标题, "创建一个基于类的视图"不是, "基于类的视图"更糟糕.

Django how-to example

每一个都是对一个问题的答案, 或问题: 我如何...? 每个标题前面都可以清楚地写上 "如何" 二字. 每一个都是一个配方, 带你完成一个特定任务所需的步骤.

尽管教程和怎么做指南都是为用户的需要服务的, 但教程是由知道用户需要知道什么的作者主导的, 而怎么做指南则是由提出问题的用户主导的.