写文档的正确方式(WIP)

写文档这事,有一个需要知道的秘密:写文档不是一件事,是四件事。

原作者Daniele Procida
本文翻译自Divio
翻译:Jonir Rings
校对&润色:Serene He,透明人383,Cyus

对于使用软件而言,如果没有使用正确方式编写的文档,即使再努力也是做着无用功。
关于写文档这事,有一个不为所知的秘密:写文档不是一件事,是四件。
分别是:tutorials教程,how-to guides指南,explanation解释,technical reference技术参考
他们代表四种不同的功能,有四种不同的编写方式。了解到这层含义,才能大举提升软件文档编写的效果。

序言

你的软件多棒都没关系,只要文档不够好,就不会有人会去用,因为人家学不会啊。
即便由于某些原因而别无选择只能使用,如果没有好的文档,用户也没法有效率地使用软件,或者不会按你想的方式去用。
几乎每个人都知道这个,几乎每个人也都知道他们需要好文档,而且大多数人也尝试了去编写好文档。
然而,大多数中的大多数,还是失败了。
通常,原因并不是因为他们不够努力,通常,只是他们努力方向错了。
我将告诉你如何提升你的文档,不是让你更努力去写,而是让你写正确。正确的方式是更容易的方式,更容易写,也更容易维护。
对于管理文档,有几个一直都像是秘密却不应该成为秘密的简单原则。
如果你能将这几个原则应用于实践,我向你保证,你的文档会变得更好,你的项目、产品、团队也会更加成功。

秘密

文档应该包含四种功能并按照这四种功能来组织:教程,指南,解释,技术参考。
它们每个都有各自迥然的编写模式。使用软件的用户在不同时间不同场合下需要对应种类的文档,所以软件就得必须要写完所有四种类型的文档。
文档需要按照这四种功能来分类,并且保证各自分离、互不重合。

教程:是面向学习的。让新人可以快速上手。是课程。类比:教你家孩子如何下厨。

how-to指南:是面向目标的。演示如何解决特定问题。是一系列步骤。类比:烹饪书上的一个菜谱。

解释:是面向理解的。就是解释。提供背景信息和前因后果。类比:一篇描述某门烹饪技术历史的文章。

技术参考:是面向信息的。描述技术的机制。必须准确且完整。类比:一个维基百科参考页面。

这个分类让作者和读者都能知道什么信息在哪儿。它告诉了作者怎么写、写什么、写在哪儿。这节省了作者和信息纠缠的时间,因为作者们总是想把信息用更有意义的结构来组织;而这种分类下,一种文档只有一个任务。
事实上,那些没有明确或者隐含遵守这个分类表的文档都难以维护,因为分类表中的每个分类都区别于其他分类,而那些不按照分类表来组织的文档,立马就会朝多个方向发散,然后变得不可控、不可维护。
当你理解了这个结构,它也能变成一个分析改造现有文档的得力工具,理解何处需要提升。
项目文档
你也许会问,那么像changelog、contribution规则、以及其他一些项目信息该放到这个分类的哪部分呢?答案是它们并不需要放进去,因为它们更像是项目文档,而不是软件文档。所以给它们一个合适的名字,然后和其他材料放一起就行。
有了这个前提,那就来瞧瞧这个四个功能分类的细节吧。
教程
教程是一系列手把手教读者如何完成某种项目的课程。它在你项目中就是来教会初学者完成某些事的。
它完完全全就是面向学习的,需要强调的是,它面向的是“学会如何做某件事”而不是“学懂某件事”。
你是一位老师,你将对学生的所作所为负责。在你的指导下,你的将执行一系列操作,直到结束。
何时结束,做什么操作,都由你决定,当然这是麻烦又困难的决定。结束的点必须要有意义,且对真·新人具有可操作性。
想象一下教小孩子下厨。
你教小孩子做了什么饭菜并不重要,重要的事孩子对于下厨能乐在其中、取得了自信,还想再做一次。
小孩子通过下厨过程中做过的各个环节,将学会下厨中的重点:在厨房中下厨到底是怎么一回事——如何使用厨具,如何处理食材等等。
因为使用软件就像是下厨,是一种手艺。它是一种知识,但是属于实践类的知识,而非理论知识。当我们学习一门手艺或者技巧时,总是从实操开始的。
教程中最重要的事就是:学习者能搞清剩下的文档以及软件本身。
大部分的软件都只有很糟糕的(甚至没有)教程。教程的作用是将你的学习者转变为用户。糟糕的文档或者没有文档,都会让你的软件错失新用户。
好的教程十分难写。它要对新手实用、容易遵循、有实际意义且健壮。
如何编写好的教程
允许用户通过实践来学习
一开始,我们学什么都是通过实践,一如我们学习说话和走路。
在你的软件教程中,你的用户也是通过实践学习。不同的是他们跟着你的教程学习时,会覆盖很多种工具和操作,从简单到复杂逐渐构建。
让用户上手
用户的第一步完全可以像婴儿学步一样手把手来教会。而一开始教给用户的做法可以不用像是经验老练者的做法,甚至可以不用是“正确”的做法:对于初学者的教程并不是最佳实践手册。
教程的目的是让你的用户起航,而不是直接到达目的地。
保证你的教程能运作
你作为教师的工作之一就是让初学者保有自信:在软件中,在教程中,在教学中,以他们自己的能力完成被要求的任务。
有许多种方法完成这项工作。友善的语气可以,一致的遣词造句可以,随着内容而推进的逻辑也可以。但最为重要的一件事还是教程中让初学者去完成的那件事,一定能运作。初学者要看到你说过会起效果的操作一定会起效果。
如果用户的操作产生了错误或者预料外的结果,你的教程就算是失败了——即便不是你的错。如果你在你学生的身边,你倒是可以帮他们一把,但是如果他们是在独自阅读你的文档,你就无能为力了——因此你必须防患于未然,提前避免意外发生。当然说着容易做着难。
保证用户立即见到结果
学生该做的每一件事,无论多小多大都应该易于理解。如果你的学生连续两页都在做些奇怪的难以理解的事,还没见到结果,那这件事就太长了。每个操作的效果都应该尽可能快的明显可见,并且和操作的关联也要清晰紧密。
教程每个章节的总结或者章节整体应该具有明确意义。
让你的教程可重复
你的教程必须是可以重复的,这并不是件容易事:来读你教程的人可能有不同的经验背景、用不同的操作系统和工具。更甚者,他们所使用的软件和资源本身也会随着版本发生变化。
而你的教程需要和它们完美工作,每一次都要。
因此教程很不幸的就需要定期的细致测试以保证它们依然能运作。
专注在具体步骤上,而不是抽象概念
教程需要是具体的,构建在特定的操作及产出上。
引入抽象概念的诱惑是相当大的;他毕竟是计算设备的力量之源。但是我们学习的过程都是从特定具体走向通泛抽象。让学生再领会具体操作之前就让他理解各种抽象级别,无疑是差劲的教学。
只提供最少的必要解释
不要解释学生完成教程所用不到的东西。扩展讨论是很重要,但是在教程中,它只会成为妨碍和分散点。仅有最少的知识点才是最适合的,然后扩展知识点,放上引用链接就行。
只专注于用户需要操作的步骤
教程需要专注于手头的任务。也许你介绍的命令有一堆的其他选项,或者有多种方法访问某个API,这都无所谓:现在,目前,你的学生不需要知道这些。
指南
指南会带着读着一步步操作来解决真实问题。
指南就像菜谱,直接教你制作某道菜。就像是“如何创建一个web表单”、“如何绘制一个三维数据集”、“如何启用LDAP认证”等。
指南完全是目标面向的。
指南拥有清晰的目标,它解决特定的问题。它告诉有基础知识的人如何完成某些事。
指南和教程的区分很明显,指南是对初学者根本想不到的那种问题的回答。
指南会假定用户拥有某些知识和理解力,假定用户知道怎么完成基本的操作和使用基本的工具。
软件文档中的指南一般都写得不错,因为他们既有趣又简单。
如何写好指南
提供一系列步骤
指南必须包含一个步骤表,然后需要按顺序执行。用户不见得需要从最初的步骤开始,但是得找到一个合理的起点。指南应该是可靠的,但是并不需要像教程那样钢铁般的可靠,只要对于有基础知识的人而言,可以推导出相应的解决方案就行。
聚焦于结果
指南必须要聚焦于实现具体目标。其他所有的东西都是分散点,跟教程一样,详细的解释也不应该出现在这儿。
解决一个问题
一个指南解决一个问题。这便是指南区别教程的一点。当读者阅读一个指南时,他会知道他要实现什么,但不见得知道如何实现——然而在教程中,你要负责决定读者需要知道的内容。
不要解释概念
指南中不要去解释事物,那不是讨论这类的地方;那只会妨碍操作。如果解释很重要很必要,那就给个链接。
允许一些灵活性
教程可以允许实际操作存在部分出入,这样的灵活性能让用户学到如何处理类似问题,适配略微差异的系统或者配置文件。这样一来,指南就能适应于你设想之外的场景。
适当留白
实际效用重于完整性。教程需要端到端的完整,而指南不需要,指南可以从任意你觉得合适的地方开始和结束。你不用把所有相关的事物都提及一遍,一个膨胀的指南并不能帮你的用户快速解决问题。
取个好名字
指南的标题应该告诉用户具体要做什么。“如何创建一个基于类的视图”这种的标题,而不是“创建基于类的视图”甚至更糟“基于类的视图”。
参考
参考属于“对原理的原理描述”以及如何操作。
参考只有一个任务:描述。它们是由代码所决定的,那也是它们所要描述的东西:关键类、函数、API等等,因此它们也会列出函数、字段、属性、方法,并陈述如何使用这些。
参考是面向信息的;那即是说参考会包含很多的范例来描述用法,但它并不应该尝试去解释基础概念,或者如何完成常见任务。
参考应该简洁切题。如果用烹饪来类比,就是某个食材的百科全书文章,描述了它的起源、表现、化学成分以及如何烹煮。
值得注意的是,参考的描述的确要包含“如何使用”这种基础信息:如何实例化一个类,如何调用特定方法,或者给某个函数传递参数的注意事项。然而这只是函数技术参考的一部分,值得强调的是一定不要和指南混淆。技术参考描述了软件的的正确用法,而指南则是展现如何完成特定目标,它们并不相同。
对于某些开发者,技术参考是他们唯一能想到的文档类型。他们已经对自己的软件了如指掌,也知道如何使用。而他们所能想到的就是其他人也需要这个软件的技术信息。
参考资料相对容易些好,某种程度上甚至能自动生成,当然自动生成还从未真正完全满足需要过。
如何写好参考
围绕代码编写参考文档
让参考文档和代码拥有同样的结构,从而使用户可同时导航到代码和文档上。这也能让会维护人看到哪里有文档缺漏或者需要更新。
保持一致
在参考中,结构、语气、格式都必须保持一致性,就如同百科全书一样。
除了描述别做其他
参考的唯一工作就是描述,尽可能清晰,尽可能全面。而其他的东西(解释、讨论、指令、猜测、观点)都会是分散点,还会使得难以维护。只有在必要的时候才提供例子来描述。
保证准确
参考的描述需要保证准确且紧跟变化。实际机制和你的描述之间的任何不一致,都会使得用户犯迷糊。
解释
解释,或者讨论,用以阐明某个话题。它可以扩展文档对话题的覆盖面。
解释是面向理解的。
解释也能被同等理解为“讨论”。它是一个机会,让文档阅读进入轻松状态,回溯到软件开始的地方,从更宽更高的视野观察,或者完全不同的视角描述等等。你可以想成讨论型文档是放在空闲时间而不是编码时期阅读的。
这类的文档极少是可以撰写,大多数情况下是作为片段分散在其他类型文档中。有时候这类事存在的,但是确是“背景和其他”这类不能很好分辨其用途的名字。
讨论型文档可能比它看上去更难编写——事物在被明确问及时更容易直接回答,当什么都没问的时候,就如同白纸一样让你不知从何说起。
这类的话题并不像指南一样是由你想完成的任务来确定的,也不像教程一样是由你想让用户学到的东西来确定的,也不像参考资料一样由原理来决定。它是由你认为每次讨论的合理范畴来确定的,所以这类话题的划分有时就有点武断或者任性。
如何写好解释
提供上下文
解释是一个放背景和上下文的好地方。例如:“Django中的Web表单以及如何处理”、“搜索并使用Django CMS”。
它们用于解释“为什么”事物是如此——设计意图,历史原因,技术局限等等。
讨论一下替代项和观点
解释是可以把替代项也引入讨论的,同样的问题也也许有多个方法。譬如一篇描述Django部署的文章,它的确适合考虑并评估一下不同Web服务器选项的差异。
讨论有时候甚至能考虑提高相反意见的价值评估,例如:测试模块是否应放在包目录中。
不用指导或者提供技术参考
解释应该做的就是其他部分文档所没做的事。所以它不是指导用户该怎么做某件事的地方,也不应该提供技术性描述。这类的功能已经有其他部分提供了。
关于文档结构
为什么不那么明确?
现在结构很清晰了,它也能运作,但是各分类之间界限却依然不太明显。下面就是每个文档的特性与其他文档重叠的部分构建的一个象限图。

教程和指南相似,因为他们都专注于描述实际的步骤,其外指南和技术参考都是实际工作编码中需要的。参考与解释也很相似,因为它们都有跟理论知识相关。而转了一圈最后教程和解释也相似,因为它们在学习的时候比工作的时候更有用。
学习时有用 工作时有用
实际步骤 教程 指南
理论知识 解释 参考
因为上面各文档的的重叠,它们之间被混淆也不足为奇。
虽然找一些特定的案例比较困难,但是很多实际的文档都或多或少实践了这四种分类方法。
某些文档则完全采取了这种分类法,包括Django、django CMS。而这种分类法证明了它的价值。
关于分析
本文中对文档的分析基于多年编写维护文档的经验,以及关于一直以来对于如何提升文档思考。
其外还来自大量规章制度中的高可靠性原则。譬如教程的概念中有一个教学性基础:一个教师和一个学生,使用软件根据对通用原则的抽象理解遵循具体操作步骤制作某个东西或者处理某个特殊情况。
让文档动起来
最让文档维护者头疼的一件事就是并没有文档该做什么事的清晰描述。他们写了又写,然后发现很难将文档按照满意的方式组织在一起。
这个分类法的结构通过清晰的区分各文档间的差别然后将它们分离开来,解决了上述问题。使得文档更好编写和维护,也更容易使用和查找。
文档并不会自己就写出来了,但是现在有可能不再去和糟糕的定位、不清晰的范畴、对是否应放进某个区块是否使用某个风格的疑惑等等,拌在一起的了。现在文档的编写变得更清晰了:写什么,怎么写,写在哪儿。
这种分类法能给用户带来方便,因为当用户在使用软件的不同期间,都能找到对应的文档,分类法它就是为了这一刻。
着实根据这四个象限区分文档的编写,能够吸引和保持更多的用户——因为他们能更有效率的使用,这亦是软件创作者最想要的结果。
关于Divio专家系列
我们的专家都名副其实。他们之中都有10年之上的Django开发经验;我们专业性经验的深度和宽度都足以让我们提供世界级的服务。他们包含Django、django CMS以及其他知名项目的核心开发者,以及超大型系统Divio Cloud基础设施的架构等等。
新的Divio专家博客系列专注于提供这些经验。如果要获取我们的最新新闻,请订阅我们的Twitter Feed,或者订阅我们的新闻信。