Open pengkobe opened 6 years ago
原文地址: https://www.divio.com/blog/documentation/ 作者: Daniele Procida
无论你文档写得多么好，如果你不按照正确的方法去写，对你开发的软件将会是没有帮助的。
写文档的一个秘诀是，你得明白好文档是由 4 部分组成的，而不能笼统的叫作文档。
这 4 个部分各司其职，有着不同的用途，明确这一点对你写文档大有裨益，
不管你开发的软件有多好，如果你的文档写得不好，也会没人用的，尽管有时候他们没有替代的软件，必须使用你的软件，但是他们也做不到高效的使用，或按照你的想法去使用。 几乎所有人都意识到了这一点，也知道他们得写好文档，但也在积极的去尝试，但是很多人都失败了。
通常，并不是大家不努力，而是，他们没有按照正确的方法去写文档。
这篇文章我将教给大家如何写好文档的正确方法，仅仅是努力是不够的，得有正确的方法才行，而且正确的方法也意味着容易写和容易维护。 这里有一些简单的原则可以分享，说出来，可能大家都曾听说过。 如果你在写文档的过程中能够遵循这些原则，我保证你的写文肯定会写得更好，也会让你的产品和团队更加成功。
文档需要包括以下四个部分
而是每部分都有着不同的写法，使用个软件的人在不同的时期需要不同的部分，总体而言，这四个部分都是必须的。 文档必须要有清楚的结构，而且不同文档间需要区分开来
#### 入门教程 * 学习导向 * 可以让新手起步 * 可以当做一节课 **类比** : 教给一个小孩子如何使用 #### 如何使用 * 目标导向 * 讲述如何解决特点问题 * 由一系列的步骤组成 **类比** : 烹饪书中的食谱 #### 详细描述 * 理解导向 * 详细阐述与讲解 * 提供背景与场景描述 **类比** : 烹饪社会史论文 #### 技术参考 * 信息导向 * 描述具体的实现方式 * 提供精准和完善的描述 **类比** : 维基百科的参考索引
这些部分可以让作者和读者都能够明了信息的组织，能够让作者知道如何书写，书写什么，在哪写，每个部分的功能清晰明了，能够让作者组织文档结构上节省大量的时间。 事实上，如果你不在这四部分上下功夫，不将这四部分分开来，你维护文档将会非常困难。 你理解了文档的这四个部分，它将成为你分析现有文档、理解你需要从哪些方面去做提升的最好工具。
你也许会问，changelogs、代码贡献指导以及其它的一些项目相关文档如何纳入到这四个部分来呢？ 答案是它们不能纳入进来，严格来说，项目文档不是软件文档，你要做的是将这些文档命名清晰规范，做到可以和其它内容区分开来即可。 有了基本的写文档的基本框架，接下来我们将对这四个部分的内容做详细介绍。
教程的目的其实就是手把手教给读者实现一个 HelloWorld 应用，因为是以学习为导向，其实主要是为了怎么用而非是学习本身。 你需要把自己当初老师，而读者就是你的学生，你要对读者的行为负责，在你的指导下，读者应该能够通一系列的动作来实现某个东西。 关于实现什么和如何实现那就由你决定了，了解读者是一件困难得事，不过你可以使得整个过程不仅有意义而且新手实现起来没有太大的难度。 你可以类比成如何教给一个小孩子做饭菜。 你教给小孩子如何做饭菜本身不重要，重要的是让小孩子觉得这个过程很有趣，能够让他增加自信，以后也愿意继续做。使用软件就像是煮饭菜，都是一些操作相关的知识而非理论，而当我们使用一个新工具和新技能的时候，往往是通过实践开始的。 比较重要的一个点是，当读者学完教程后，能够理解文档的其余部分，同时能够了知道软件大概是什么以及如何使用了。 大多数软件项目教程都写的很差，有的甚至连教程都没有，教程能够将你软件学习者转化为用户，教程的缺失会让你无法获取新用户。 好的教程写起来也是困难的，他们需要对初学者有用才行，比如容易跟上节奏、有意义、信息又足够全。
ALLOW THE USER TO LEARN BY DOING
原文地址: https://www.divio.com/blog/documentation/
作者: Daniele Procida
无论你文档写得多么好，如果你不按照正确的方法去写，对你开发的软件将会是没有帮助的。
写文档的一个秘诀是，你得明白好文档是由 4 部分组成的，而不能笼统的叫作文档。
这 4 个部分各司其职，有着不同的用途，明确这一点对你写文档大有裨益，
简介
不管你开发的软件有多好，如果你的文档写得不好，也会没人用的，尽管有时候他们没有替代的软件，必须使用你的软件，但是他们也做不到高效的使用，或按照你的想法去使用。
几乎所有人都意识到了这一点，也知道他们得写好文档，但也在积极的去尝试，但是很多人都失败了。
通常，并不是大家不努力，而是，他们没有按照正确的方法去写文档。
这篇文章我将教给大家如何写好文档的正确方法，仅仅是努力是不够的，得有正确的方法才行，而且正确的方法也意味着容易写和容易维护。
这里有一些简单的原则可以分享，说出来，可能大家都曾听说过。
如果你在写文档的过程中能够遵循这些原则，我保证你的写文肯定会写得更好，也会让你的产品和团队更加成功。
写文档的秘密
文档需要包括以下四个部分
而是每部分都有着不同的写法，使用个软件的人在不同的时期需要不同的部分，总体而言，这四个部分都是必须的。
文档必须要有清楚的结构，而且不同文档间需要区分开来
这些部分可以让作者和读者都能够明了信息的组织，能够让作者知道如何书写，书写什么，在哪写，每个部分的功能清晰明了，能够让作者组织文档结构上节省大量的时间。 事实上，如果你不在这四部分上下功夫，不将这四部分分开来，你维护文档将会非常困难。
你理解了文档的这四个部分，它将成为你分析现有文档、理解你需要从哪些方面去做提升的最好工具。
项目文档
你也许会问，changelogs、代码贡献指导以及其它的一些项目相关文档如何纳入到这四个部分来呢？ 答案是它们不能纳入进来，严格来说，项目文档不是软件文档，你要做的是将这些文档命名清晰规范，做到可以和其它内容区分开来即可。
有了基本的写文档的基本框架，接下来我们将对这四个部分的内容做详细介绍。
入门教程
教程的目的其实就是手把手教给读者实现一个 HelloWorld 应用，因为是以学习为导向，其实主要是为了怎么用而非是学习本身。
你需要把自己当初老师，而读者就是你的学生，你要对读者的行为负责，在你的指导下，读者应该能够通一系列的动作来实现某个东西。
关于实现什么和如何实现那就由你决定了，了解读者是一件困难得事，不过你可以使得整个过程不仅有意义而且新手实现起来没有太大的难度。
你可以类比成如何教给一个小孩子做饭菜。
你教给小孩子如何做饭菜本身不重要，重要的是让小孩子觉得这个过程很有趣，能够让他增加自信，以后也愿意继续做。使用软件就像是煮饭菜，都是一些操作相关的知识而非理论，而当我们使用一个新工具和新技能的时候，往往是通过实践开始的。 比较重要的一个点是，当读者学完教程后，能够理解文档的其余部分，同时能够了知道软件大概是什么以及如何使用了。 大多数软件项目教程都写的很差，有的甚至连教程都没有，教程能够将你软件学习者转化为用户，教程的缺失会让你无法获取新用户。
好的教程写起来也是困难的，他们需要对初学者有用才行，比如容易跟上节奏、有意义、信息又足够全。
如何写一个好的教程
ALLOW THE USER TO LEARN BY DOING