「译」如何撰写技术文档

原文来自 What nobody tells you about documentation，本文是本人整理翻译而成。

关于如何写好一个完善的软件文档，这里应当是有四要素，而不是一个。它们分别是：教程，操做指南，说明和技术参考。它们表明四种不一样的目的和功能，而且须要四种不一样的方法来建立它们。了解这一点的含义有助于改进大多数的软件文档-一般会有很是好的效果。

前言

软件有多好并不重要，由于若是文档不够好，人们就不会使用它。

即便因为某种缘由他们不得不使用它，这是由于他们没有选择，没有良好的文档，他们将不会有效地使用它或者你喜欢它的方式。几乎每一个人都明白这一点。 几乎每一个人都知道他们须要良好的文档，而且大多数人都试图建立好的文档。但大多数人都失败了。一般这不是由于他们不够努力，而是由于他们没有找到正确的方式。

在本文中，我将解释如何使您的文档更好，而不是经过更加努力，而是经过正确的方式。 正确的方法是更简单的方法 - 更容易编写，更容易维护。

有一些很是简单的原则能够管理少见的有拼写的文档。 它们彷佛是一个秘密，尽管它们不该该是。若是您可以将这些原则付诸实践，它将使您的文档更好，您的项目，产品或团队更成功 - 这是一个承诺。

文档须要包含并围绕其四个不一样的功能进行构建：教程，操做指南，说明和技术参考。 他们每一个都须要一种独特的写做模式。 使用软件的人在不一样的环境中须要这四种不一样的文档 - 所以软件中一般都须要它们。而且须要围绕它们明确地构建文档，而且它们必须保持独立且彼此不一样。

教程	操做指南	说明	技术参考
以学习为导向	以目标为导向	以理解为导向	以信息为导向
容许新人入门	展现了如何解决特定问题	解释	描述软件
是一个课程	是一系列步骤	提供背景和上下文	是准确且完整的

这种划分使做者和读者明白了哪些信息在哪里。 它告诉做者如何编写，编写什么以及在何处编写它。 它使做者免于浪费大量时间来尝试将他们想要传达的信息篡改为有意义的形状，由于这些文档中的每一种只有一个工做。

事实上，维护良好的文档很是难以隐含或明确地识别该方案的象限。 每种类型的要求都与其余要求不一样，所以任何未能保持这种结构的文档尝试都会受到影响，由于它会当即被拉向不一样的方向。

一旦理解告终构，它就成为一种很是有用的工具，用于分析现有文档，并了解须要采起哪些措施来改进它。

关于项目文件您可能会问：更改日志，贡献策略以及有关项目的其余信息在哪些方面适合此方案？ 答案是他们没有 - 由于严格来讲，他们是项目文档，而不是软件自己的文档，

它们能够简单地与其余材料一块儿保存在适当命名的部分中 - 只要它们没有混合在一块儿。

考虑到这一点，让咱们探讨四个关键功能中的每个。

教程

教程是让读者经过一系列步骤来完成某种项目的课程。 它们是您的项目所须要的，以向初学者展现他们能够用它实现某些目标。

他们彻底以学习为导向，具体而言，他们的目标是学习如何而不是学习。

你是老师，你负责学生的工做。 在您的指导下，学生将执行一系列操做以达到目的。

结束和行动取决于你，但决定他们应该作什么多是艰苦的工做。 最终必须有意义，但对于一个完整的初学者也是能够实现的。

考虑一个教孩子作饭的比喻。

你教孩子作饭的内容并不重要。 重要的是，孩子以为它颇有乐趣，而且有信心，并但愿再次这样作。

经过孩子所作的事情，它将学习烹饪的重要事项。 它将了解在厨房里使用餐具来处理食物是什么感受。

这是由于使用像烹饪这样的软件是一个技巧问题。 它是知识 - 但它是实践知识，而不是理论知识。 当咱们学习新工艺或技能时，咱们老是开始学习它。

重要的是，完成教程后，学习者就可以理解其他的文档和软件自己。

大多数软件项目都有很是糟糕或不存在的教程。 教程将使您的学习者变成用户。 错误或缺乏的教程将阻止您的项目获取新用户。

好的教程很难写。 它们须要对初学者有用，易于遵循，有意义且极其健壮。

容许用户学习

一开始，咱们只是经过作才学到任何东西 - 这就是咱们学会说话或走路的方式。

在您的软件教程中，您的学习者须要作的事情。 在学习本教程时，他们所作的不一样事情须要涵盖普遍的工具和操做，从最简单的工具和操做开始，再到更复杂的工具和操做。

让用户开始

若是你的初学者的第一步是手持婴儿步骤，这是彻底能够接受的。 若是初学者要作的不是有经验的人的方式，或者即便它不是“正确的”方式，那也是彻底能够接受的 - 初学者的教程与最佳实践的手册不一样。

教程的目的是让学习者开始他们的旅程，而不是让他们到达最终目的地。

请确认您的教程工做

做为导师，你的一个工做就是激发初学者的信心：在软件，教程，导师中，固然，还有他们本身实现所要求的能力。

有不少事情能够促成这一点。 友好的语气和语言的一导致用以及材料的逻辑进展都有所帮助。 但最重要的是，你要求初学者作的事必须奏效。 学习者须要看到你要求他们采起的行动会产生你说他们会有的效果。

若是学习者的动做产生错误或意外结果，那么您的教程就会失败 - 即便这不是您的错。 当你的学生和你在一块儿时，你能够拯救他们; 若是他们本身阅读你的文档你就不能 - 因此你必须提早防止这种状况发生。 毫无疑问，这提及来容易作起来难。

确保用户当即得到结果

学习者所作的一切都应该是能够理解的，不管多么小。 若是你的学生在看到结果以前必须作两页的奇怪和难以理解的事情，那就太长了。 每个行动的效果应尽快显现和明显，而且应明确与行动的联系。

教程的每一个部分或整个教程的结论必须是有意义的成就。

使教程可重复

您的教程必须可靠地重复。 这不容易实现：人们将使用不一样的操做系统，经验和工具水平来实现它。 更重要的是，他们使用的任何软件或资源极可能在此期间发生变化。

每次教程都必须适用于全部这些教程。

不幸的是，教程须要按期和详细的测试，以确保它们仍然有效。

关注具体步骤，而非抽象概念

教程须要具体，围绕特定的，特定的行动和结果。

引入抽象的诱惑是巨大的;毕竟大多数计算是如何得到它的力量的。可是全部的学习都是从特定的，具体的到通常的和抽象的，而且要求学习者在他们甚至有机会掌握具体内容以前欣赏抽象层次是教学很差。

提供最低限度的必要解释

不要解释学习者为了完成教程而不须要知道的任何内容。扩展讨论很重要 - 只是不在教程中。在教程中，这是一个障碍和分心。只有最低限度是合适的。相反，请连接到文档中其余地方的解释。

只关注用户须要采起的步骤

您的教程须要专一于手头的任务。也许您引入的命令有许多其余选项，或者可能有不一样的方法来访问某个API。不要紧：如今，你的学习者不须要了解那些才能取得进步。

操做指南

操做指南使读者了解解决实际问题所需的步骤。

它们是食谱，实现特定目标的方向 - 例如：如何建立Web表单; 如何绘制三维数据集; 如何启用LDAP身份验证。

他们彻底以目标为导向。

若是你想要一个比喻，想一想一个食谱，准备吃东西。

配方有明确的定义结束。 它解决了一个具体问题。 它代表某人 - 能够假设他已经拥有一些基本知识 - 如何实现某些目标。

操做指南与教程彻底不一样。 操做指南是对真正的初学者甚至没法制定的问题的回答。

在操做指南中，您能够假设一些知识和理解。 您能够假设用户已经知道如何执行基本操做并使用基本工具。

提供一系列步骤

操做指南必须包含须要按顺序执行的步骤列表（就像教程同样）。你没必要从一开始就开始，只是在一个合理的起点。操做指南应该可靠，但它们不须要具备教程的铸铁可重复性。

关注结果

操做指南必须注重实现实际目标。别的什么都是分心。与教程同样，详细说明在这里不合适。

解决问题

操做指南必须解决特定的问题或问题：我如何...？

这是操做指南与教程不一样的一种方式：当涉及到操做指南时，能够假定读者知道他们应该实现什么，但还不知道如何 - 而在本教程中，您有责任决定读者须要了解的内容。

不要解释概念

操做指南不该该解释事情。这不是那种讨论的地方;他们只会妨碍行动。若是解释很重要，请连接到它们。

容许一些灵活性

操做指南应该容许稍微不一样的方式来作一样的事情。它须要足够的灵活性，用户能够看到它将如何应用于与您描述的示例略有不一样的示例，或者了解如何使其适应与您假设的略有不一样的系统或配置。除非你想到的确切目的，不然不要那么具体，指南对任何事情都没用。

随时离开

实际可用性比完整性更有价值。教程须要完整，端到端的指南;操做指南没有。它们能够在适合您的地方开始和结束。他们不须要说起全部要说起的内容，只是由于它与主题相关。臃肿的操做指南没法帮助用户快速得到解决方案。

标题对用户友好

操做方法文档的标题应该告诉用户确切的内容。如何建立基于类的视图是一个很好的标题。建立基于类的视图或更糟糕的是，基于类的视图不是。

技术参考

技术参考是机器的技术说明以及如何操做。

技术参考只有一个工做：描述。它们是由代码决定的，由于它们最终描述的是：关键类，函数，API等等，它们应该列出函数，字段，属性和方法等内容，并列出如何使用它们。

参考资料是面向信息的。

经过各类方式技术参考能够包含示例来讲明用法，但它不该该尝试解释基本概念，或者如何实现共同任务。

参考资料应该是严格的，切中要害的。

烹饪类比多是一篇关于一种成分的环球文章，描述了它的来源，它的行为，它的化学成分，它是如何烹饪的。

请注意，描述确实包括如何使用机器的基本描述 - 如何实例化特定类，或调用某个方法，或者在将某些东西传递给函数时必须采起的预防措施。然而，这仅仅是其做为技术参考的功能的一部分，而且强调不要与操做指南相混淆 - 描述软件的正确使用（技术参考）与显示如何使用它来实现某一目的不一样（方法文档）。

对于一些开发人员，参考指南是他们能够想象的惟一文档。他们已经了解他们的软件，他们知道如何使用它。他们能够想象其余人可能须要的是关于它的技术信息。

参考材料每每写得很好。它甚至能够在某种程度上自动生成，但这自己就不够了。

构建代码周围的文档

为参考文档提供与代码库相同的结构，以便用户能够同时导航代码和文档。这也将有助于维护人员查看缺乏参考文档或须要更新的位置。

始终如一

在技术参考中，结构，音调，格式必须一致 - 与百科全书或字典一致。

不要作任何描述

技术参考的惟一工做是尽量清楚和完整地描述。其余任何事情（解释，讨论，指导，推测，意见）不只会分散注意力，并且会使其更难以使用和维护。提供示例以在适当时说明说明。

避免使用参考材料来指导如何实现事物，超出使用软件的基本范围，而且不容许对主题的概念或讨论进行解释。相反，请酌情连接到操做指南，说明和教程。

准确性

这些描述必须准确并保持最新状态。机器与您对它的描述之间的任何差别都将不可避免地致使用户误入歧途。

说明

说明或讨论，阐明和阐明特定主题。它们拓宽了文档对主题的覆盖范围。

他们是理解导向的。

说明一样能够描述为讨论。它们是文档放松和退回软件的机会，从更普遍的视角，从更高层次甚至从不一样角度阐明它。您能够想象一个讨论文档是在闲暇时阅读，而不是在代码上阅读。

这部分文档不多明确建立，相反，解释的片断分散在其余部分中。有时，该部分存在，但有一个名称，如背景或其余笔记，并无真正公正的功能。

讨论不像看起来那么容易建立 - 当你有一个问题的起点时，直接解释的东西就不那么容易了，当你有一个空白页面而且必须写下一些关于它的东西时。

主题不是由您想要实现的特定任务定义的，例如操做指南，或者您但愿用户学习的内容，例如教程。它不是由一块机器定义的，好比参考材料。它是由您认为一次尝试覆盖的合理区域定义的，所以讨论主题的划分有时可能有点武断。

提供上下文

说明是背景和上下文的位置 - 例如，Web表单以及如何在Django或Search和django CMS中处理它们。

他们还能够说明为何事情如此 - 设计决策，历史缘由，技术限制。

讨论替代方案和意见

说明能够考虑替代方案，或同一问题的多种不一样方法。例如，在关于Django部署的文章中，考虑和评估不一样的Web服务器选项是合适的，

讨论甚至能够考虑并权衡相反的意见 - 例如，测试模块是否应该在包目录中。

请勿指导或提供技术参考

说明应该作的事情是文档的其余部分没有的。指示用户如何作某事并非解释的地方。它也不该该提供技术描述。文档的这些功能已在其余部分中处理。