Tutorials

教程

教程是引导读者通过一些列步骤来完成某种项目的课程. 它们是你的项目所需要的, 以便于向初学者展示他们可以用它实现一些东西.

这些文档完全是"学习导向"的, 而且具体来说, 它们是导向与学习"如何做"而不是学习"它/某个东西".

你是一位老师, 你对学生的行为负责. 在你的指导下, 学生将进行一系列的行动, 来达到一些结果.

结果和行动都是由你来决定的, 但是决定它们应该是什么可能是一项艰巨的工作. 结果必须有意义, 但是也要对初学者来说是可实现的.

重要的是, 在完成教程后, 学习者能够理解文档的剩余部分, 还有软件本身.

大多数软件有非常糟糕的 - 甚至没有 - 教程. 教程使得你的学习者成为用户. 一个糟糕的教程, 或者缺失教程, 会阻止你的项目获取新的用户.

在描述四种文档的章节中, 这个章节是最长的 - 这是因为教程是最容易被误解, 而且是最难被做好的. 最好的教学方式是老师在场, 与学生互动. 这很难做到, 而且我们的书面教程充其量只是一个远非完美的替代品. 这就更需要我们对它们给予特别的关注.

教程需要对初学者有用, 易于理解, 有意义, 非常鲁棒/健全, 而且保持最新. 你可能发现, 编写和维护教程需要的时间和精力, 和其它三个部分加起来一样多.

和烹饪类比

试着类比一下, 教一个孩子烹饪.

你教给孩子的其实不是真正重要的. 重要的是, 孩子觉得它很有趣, 并且获得了信心, 并且想要再做一次.

通过孩子所做的事情, 他将学到关于烹饪的要点. 他将学到在厨房里是什么感觉, 使用厨具, 处理食物.

这是因为使用软件, 就像烹饪, 是一件手艺活. 它是知识 - 但是它是实用的知识, 而不是理论知识.

在我们学习一项新的手艺或技能时, 我们总是通过做来开始学习它.

如何写好的教程

使用户在动手做中学习(Learning by Doing)

在开始时, 我们只能通过动手做中学习 - 这正是我们学习说话, 或者走路的方式.

在你的软件教程中, 你的学习者需要做一些事情. 他们跟着你的教程做不同的事情, 需要涵盖广泛的工具和操作, 需要从一开始最简单的操作到更复杂的操作.

使用户能够开始上手

在初学者的第一步使用手把手的方式进行教学, 这是完全可以接受的. 在初学者做的事情和有经验的人做的事情不一样, 甚至不是"正确的"方式, 也是完全可以接受的 - 初学者的教程和最佳实践手册是不一样的.

教程的重点是让学习者开始他们的旅程, 而不是让他们到达最终目的地.

保证教程能够正常工作

你作为导师的工作之一就是激发初学者的信心: 在软件中, 在教程中, 在教程后, 当然还有对他们自己实现所要求的事情的能力.

很多事情有助于此. 友好的语气有帮助, 友好的语言以及材料中的逻辑递进同样有帮助. 但是唯一重要的事情是你要求初学者做的事情必须能工作. 学习者需要看到, 你要求他们做的行动会产生你所说的效果.

如果学习者的行动产生了一个错误或者预期外的结果, 你的教程就失败了 - 即使这不是你的错. 当你的学生在你旁边的话, 你还可以救他们, 但如果他们自己阅读文档的话, 你就救不了了 - 所以必须提前防止这种事情的发生. 毫无疑问, 说起来容易做起来难.

保证用户能立刻看到结果

学习者所做的一切都应该能够产生一些可以感知的结果, 无论多么微笑. 如果你的学生在看到结果之前, 必须做完两页奇怪和难以理解的事情, 那过程就太长了. 每个行动的效果都应该展现出来, 越快越好, 并且行动和结果之间的联系应该是清晰的.

教程的每一节或者整个的结论, 必须是一个有意义的成就.

使你的教程可重复

教程必须是可以可靠可重复的. 这一点并不容易做到: 使用不同操作系统, 拥有不同经验, 使用不同工具的人会来学习. 更重要的是, 他们使用的任何软件或资源都有可能在这期间发生变化.

教程必须对所有人都奏效, 而且每次都应如此.

所以不幸的是, 教程需要定期和详细的测试, 以确保它们仍然有效.

专注在具体步骤, 而不是抽象概念

教程需要具体, 围绕着具体, 特定的行动和结果来构建.

引入抽象的诱惑是巨大的; 毕竟大多数计算机领域的事情都是由此获得力量. 但是, 所有的学习步骤都是从特定的, 具体的开始, 再到一般的, 抽象的. 让学习者在他们还没有掌握具体的东西之前, 就要他们去接受抽象层次, 这是糟糕的教学.

仅提供最低限度的必要解释

不要解释任何学习者为完成教程而不需要知道的事情. 扩展性的讨论是很重要的 -- 但是不应该在教程中. 在教程中, 它是一种障碍和干扰. 只有最低限度的解释才是适合的. 作为替代, 链接到文档中的其他地方去解释.

只关注用户需要做的步骤

你的教程需要专注于手上的任务. 也许你介绍的命令有很多其他选项, 业余有不同的方法来访问某个 API. 这都不重要: 现在, 你的学习者不需要为了取得进展而知道这些.

Divio 文档中的例子

来看看 我们的教程.

尤其是看 Django 的教程. 教程做出的承诺是: 如果你有学习教程的基本知识, 并按照它的指示进行操作, 你将获得一个可以工作的 Django Web 应用程序, 包括 Postgres 数据库, S3 媒体存储等等. 作为教程, 它必须实现这一承诺.

注意它不会告诉你将学到什么, 而指示告诉你需要做什么. 学习来自于这样做. 教程对将要做什么和执行的顺序负责.