如何撰写技术文档?(译)

原文地址:What nobody tells you about documentation

如果你编写的文档有问题,那么不管你多面努力的完善文档也不会对你的软件产生积极意义。

要想写好软件文档,你必须要知道并不只是有一种文档类型,而是四种类型的软件文档。

分别是教程、指南、解释、参考。四种类型的文档分别代表这不同的功能,你只要理解好该写什么类型的文档才能使得你的软件文档具有意义。

介绍

如果你的技术文档写得不够好,那么你软件写得再好,人们也是不会去用的。

假如有人不得不去使用,没有好的文档会造成用户无法有效的和按照你预想的方式去使用你的软件。

几乎所有的人都知道一份好的技术文档的重要性,他们也在尽量的编写一份好的文档,但大多数人失败了。不是因为他们没有用心去写,而是因为编写文档的方式是错误的。

在这里我会告诉你用正确的方式去编写一份好的文档,书写更简单、维护更轻松。

如果你能将我说的技巧应用在编写文档中,那么你将会提供出更好的文档,也会使得你的软件、产品、团队更容易成功。

编写技术文档的秘密

技术文档可以划分为教程、指南、解释、技术参考四个方面,每一种类型需要用不同的写作模式。做为一个软件开发者,你需要在不同的时间提供不同类型的文档,所以一般来说,你需要为你的软件编写这四种类型的文档。

技术文档需要按照这四种类型来组织同时将它们区分开,但又要让它们相互间具有链接关系。

  • 教程
    • 以学习为导向
    • 可用于帮助新手使用
    • 课程的形式

教孩子厨艺

  • 指南
    • 以目标为导向
    • 说明如何解决一个特殊的问题
    • 系统化的步骤

一本关于厨艺的书籍

  • 解释文档
    • 以理解为导向
    • 解释原理
    • 提供问题背景以及上下文

一篇关于烹饪社会史的文章

  • 参考文档
    • 以信息输出为导向
    • 关于软件的描述
    • 准确且完整的

一篇百科全书文章

按上述将技术文档进行划分,可以让作者和读者清楚的知道从哪去获取什么样的信息。告知作者如何写?写什么?再哪写。这样明确的区别让作者不必浪费时间将所有的信息糅杂在一起,因为每一种类型的文档都有它自己的用户和意义。

事实上,不按上述方式划分编写的技术文档是非常难以维护的,因为它同时包含了多个维度的信息而显得不伦不类的。

一旦你理解了上述的文档分类方式,那么你将能够很好的分析当前文档以及改进文档,从而更好的维护。

项目文档

你也许会问,更新日志、贡献者记录以及其它的项目记录信息如何匹配到上诉的分类中?答案是不需要,严格的说,项目文档并不是项目本身的一切信息。

可以将这些信息进行单独的分类命名而不要揉合到其它类型的文档中。

接下来,我们来看一下每一种类型文档的关键功能点。

教程

教程也是课程,通过一系列的步骤来指导用户完成一个初步的项目。通过教程来让初学者可以通过你的软件来做出一些有用的东西。

它是以学习为导向的,倾向于学习如何做而不是学习软件本身。

作为导师,你需要对你的学生负责。你的学生在你的指示下,他们会完成一系列的行为并最终实现某项功能。

课程的结果和流程步骤是难以决定的,但是必须保证结果是有意义的以及能让初学者有成就感。

就如同教导儿童厨艺一样,教导他们做什么样的菜不重要,重要的是让他们享受这个过程,获得自信并想继续下去。通过这个过程让他们学会如何切菜、摆弄厨具等。

使用软件就如同做菜、如同进行某项工艺一样。它是一种技术,偏使用,而不是理论知识。当我们学习某项技术的时候总是通过实践去学习,学习软件也是一样。

重要的是当初学者完成教程后会对余下的文档和软件本身有一个大致的认识。

大多数的软件项目的教程都不达标——教程的目的是将学习者转换为你的用户。而大多数的软件教程并不能将学习者转换为新的用户。

好的教程文档编写是很难的,它必须能被初学者接受,便于跟进,有意义和具有健壮性。

如何编写好的教程文档

  • 让初学者通过做来学习

如同学会说话和走路一样,我们通过做和实践来学习。

在你的软件教程中,你的使用者需要通过做来学习。随着教程的学习,他们需要做不同的做不同的操作,涉及软件的主要功能点。从简单的功能逐渐过渡到复杂的功能。

  • 简单好入手 最开始的教程最好一步一步的指导学习者如同教导孩子一样,通过简单的步骤就能完成,即使这个过程有瑕疵,不太规范也没关系,因为这并不是最佳实践手册。

教程的目的是带领他们进入学习的旅程,而不是带着他们走到终点。

  • 确保你的教程有意义

在学习教程的这个过程中,你扮演的角色是给予初学者自信,让他们感觉到做到做出了一些东西。

其中最重要的是你提供的指导必须确保有效,初学者根据你提供的教程指导做些去必须要得到你提到的结果。

如果初学者跟随你的教程一步一步的做下去却发生了错误,那么你的教程就是失败的,即使这并不是你的错。如果你的学生就在你的身边,那么你还能挽救,如果他们独立的在学习你的教程,那么你将很难解决他们出现的问题。所以最好的解决方案就是避免出现问。

  • 确保用户能够立马看到结果

无论学习者做了多么小的改动,他都应该能够立刻感受到结果的变化。如果你的学生学习了两页的内容还没有看到结果,那么这个学习成本是非常大的。每一步操作的结果最好能力实时清晰的表现出来并让学习者感受到。

教程的每一个章节或全篇的总结必须是有意义成就的。

  • 确保教程是可复用的

教程必须可信赖且可复用。因为用户的水平不一,使用的系统也不近相同,尽管这并不容易实现。教程必须适用于所有的用户,任何时间段。

因此教程需要进行定期和详细的测试以确保其可用性。

  • 关注具体的步骤,而不是抽象的概念

教程需要具体的,通过特定的操作和行为得到特定的结果。

一开始就介绍抽象的概念是很有诱惑力的,毕竟抽象的概念更能够展示软件的强大。但是所有的学习都是从具体到抽象的过程,并且要求用户在学习具体的内容之前就去传输抽象的概念是糟糕的教学方式。

  • 提供尽可能少的必要的解释

在学习教程的过程中,不需要向用户解释一切的概念,完成教程才是主要的目的。拓展讨论是很重要的,但是不应该出现在教程中,那会阻塞学习,使用户分心。教程中应该只给出一些必须的解释即可,对于其它的解释可以通过链接的形式给出。

  • 只关注用户需要采取的步骤

教程中需要关注当前的任务。也许你当前介绍的命令有其它的可选参数,或者具有不同的方式来访问 API。但那都不重要,这时只需要将任务进行下去即可,而一些相关的知识则不必这时提出来。

如何编写指南

用户阅读指南的目的是用来解决一个真实的问题。

它是一份特定的食谱,通往结果的方向。比如:如何在 web 页面中创建表单;如何处理三维数据;如何实现 LDAP 验证。

这些都是以目标为导向的。

打个比方,一份特定的食谱,食谱的目标是用来指导做一种吃的食物。

一份食谱有一个清晰、明确的目标。它解决某个特定的问题。它可以让具有某些基础知识的人能够通过它做到某件事,达到某种结果。

在编写指南的过程中,你可以假设用户已经具备某种基础的能力,知道怎么使用基础的工具。

如何编写良好的指南

  • 将一件事情划分成一系列的步骤

如同教程一样,指南也需要划分为一系列的步骤,用户按顺序一步一步就能解决问题。

在指南里,你不需要像教程那也写得非常基础,描述清楚每一步做什么即可。

指南应该是可信赖的,但是不需要保证可复用性。

  • 关注执行的结果

指南的目的是解决一个实际的问题,任何导致分心的东西都是不必要的,就如同在教程中一样,详细的概念解释是不必要的。

  • 解决一个问题

指南必须能解决一个特定的问题或者难点。

这也是指南区分于教程的地方,在指南中,用户一般已经具备了相关的基础知识,但是不知道如何利用这些知识来做。而在教程中,你需要决定用户应该知道哪些知识,从而利用这些知识去完成教程的任务。

  • 不要解释概念

一份指南不应该解释相关的知识点及概念。在这里用户会学到如何去完成某一个步骤而不是了解这些步骤是做什么,用到了什么东西。当然如果特别重要的知识点需要解释,可以通过一个链接的形式提供。

  • 容许一定的灵活性

在指南中,可以通过具有轻微差别的方式来达到同样的结果。这样用户可以通过有轻微差别的例子来完成指南,同时也便于适配不同的操作系统和配置。在指南中只有要实现的结果才是严格要求的。

  • 未完成完整的指南也是可以的

实际操作能力比完整的做完指南更有意义。教程需要完整的学完,而指南不需要,当指南已经解决了你的问题时就可以结束了,即使还没有将指南完整的走过。因为指南的目的就是为了解决用户的实际问题,既然问题解决了,那么其它的都不重要。

  • 指南的标题很重要

从标题应该可以指南这份指南是解决什么样的问题。

如《如何创建一个基于类的视图》就是一个好的标题,而《基于类的视图》就不那么明确

参考文档

参考文档是关于机器以及如何操作机器的技术性描述文档。

参考文档只做一件事,描述清楚事物本身。参考会涉及到代码本身,如关键的类、函数、API等。所以在参考文档中应该对类、函数、API等做一个详细的描述,同时说明如何使用。

技术参考文档一般会通过代码示例来指导用户。但是不要去介绍基本的知识点以及做一些通用的事情。

技术参考文档应该切中要点。

对于许多开发者来说,技术文档是他们唯一能提供的。因为他们已经理解了软件的工作原理,知道如何去使用它。所以他们觉得用户需要的只是软件的技术信息。

参考文档可以写得很好,某种程度上还可以自动生成参考文档,但是这是不够的。

如何编写好的参考文档

  • 按照代码层次结构来组织参考文档 将参考文档和代码的层次结构统一起来,这样在阅读代码的时候也可以很好的阅读参考文档,同时也便于维护者及时了解参考文档中的错误以及缺少,从而及时更新。

  • 一致性

在参考文档中,结构、语法、格式必须保持一致性,就像百科全书或者词典那样。

  • 仅仅是描述

在参考文档中尽可能清晰、完整的描述。解释、讨论、指示操作等不仅仅会导致分心,而且会使得文档难以维护。有必要的时候可以提供实例来说明问题。

避免在参考文档中指导如何去做某一件事情,除了软件本身的概念外,不要解释相关的概念和讨论相关的话题。当然,可以通过链接的方式给出指南、解释及教程的地址。

  • 精确性

参考文档中的描述必须是精确的而且是最新的。任何不一致的描述都可能会将用户带向误区。

解释

解释或者讨论可以阐明一个特定的话题,这可以拓展文档对某一个话题的影响力。

解释以理解为主。

如何编写好的解释性文档

  • 提供上下文环境

说明话题相关的背景和上下文,例如,如何在 Django 中处理 web 表单。

也可以用来解释为什么要这样做 - 设计的选择、历史原因、技术上的限制

  • 讨论可选方案和建议

解释说明不同的技术方案或者多种解决问题的思路。如在一篇 Django 部署的解释文档中,可能会建议使用不同类型的 web 服务器。

  • 不要指导或提供技术参考

解释性文档做的事情应该是其它类型的文档中所没有的东西。指导性文档应该在指南或者教程中,而描述性的文档应该是在参考文档中。

关于结构

为什么这种文档结构不是显而易见的?

这种文档结构清晰而且确实有效,那么为什么并不是特比的明显呢?这是因为他们之间的特点有着重叠的部分。

教程和指南都通过步骤的形式来指导用户理解和解决问题。