About_docs

来自于divio总结的一些文档方案，参考https://docs.divio.com/documentation-system/

文档的功能

文档需要包含并且围绕四种不同的功能进行构建：教程（tutorials）、操作指南（how-to guides）、技术参考（technical reference）和解释（explanation）

• 教程主要是针对想要学习的对象，最重要的就是让新人能够上手。
• 操作指南通常通过一系列步骤，能够完成一个目标。
• 技术参考，更像一本百科全书，让用户可以在其中找到所有的技术点。
• explanation：对一些概念和名词进行解释，更偏向用户理解这些内容。

功能一：教程

什么是教程：教程是引导读者手动完成一系列步骤，然后完成某项项目的课程。

ps：我理解这里的意思不仅仅是包含（1）构建项目，可能还包含（2）如何修改某个模块和（3）如何规范的提交修改后的代码等等

编写一个好的教程所需要注意的细节：

• 确保用户能够立即看到结果
• 教程可以适用于所有人。这些人可能使用与你不同的操作系统，可能水平高于或者低于你。
• 关注具体步骤和结果，而不是抽象概念。如果一定需要解释一些抽象概念，请用简洁且易于理解的方式去提供最低限度的解释，因为在教程中，详细的解释可能在步骤的进行中会形成干扰。详细的解释可以放在文档的其他部分。
• 最好能够通过一些方法排除一些可能会出现问题的步骤。例如您在网络库教程中不需要让用户去访问您的服务器ip，让用户在本地进行网络通信即可。

功能二：操作指南

什么是操作指南：操作指南可以通过一系列步骤引导读者解决项目中的实际问题。

面向人群：通常是面向有一定经验的用户。

ps：操作步骤可能是针对多个实际问题的解决方案，与issue的区别在于，它是作者提供给用户可修改的地方而不是作者没有发现的问题。

编写一个好的教程所需要注意的细节：

• 不需要完整的步骤，你可以节选完整步骤中的某些步骤来解决实际问题。
• 概念不应该在操作指南中被解释。
• 标题应该能够快速的让读者意识到这就是他们需要解决的问题。

功能三：参考指南

什么是参考指南：参考指南是全面的解释。

ps：可以使通过注释生成的文档，例如Doxygen。

编写一个好的参考指南所需要注意的细节：

• 围绕代码进行编写，保持和代码更新的同步性。

• 只对技术点、细节做描述，不做解释。
• 保持准确性。

功能四：explanation

什么是explanation：从多个角度，多个层次来解释和讨论某一些技术点、代码或者是概念。

ps：explanation可能不是一个专门的文档模块，它可能在文档的各个部分。因为在explanation的时候，如果脱离上下文可能会导致读者的理解上变得困难。

编写一个好的explanation所需要注意的细节：

• 以理解为导向，让读者可以深入理解某个技术点、代码或者是概念的来源和一些思考。

• 在编写explanation的时候需要提供上下文。
• 更多的偏向于提供客观事实，然后让用户去参与explanation和讨论某些技术点、代码或者是概念。

文档结构组织

这种结构很清晰，而且有效，但它不那么明显是有原因的，那就是功能之间会有一些特征的重叠。

ps：例如explanation可能会贯穿文档的所有地方。

• 教程和操作指南都涉及描述实际步骤。
• 操作指南和技术参考是在工作和编码时所需要的。
• 参考指南和explanation都涉及理论知识。
• 教程和explanation在学习时最有用。