四种文档的种类，以及为什么需要了解它们

前言

好的文档应更容易被撰写，更简单去维护

什么是文档(documentation)？狭义上来说多指与程序有关的说明性文本，但其实生活中大大小小的事都能是文档。常见的技术教学是一种文档，煮饭时的食谱也是一种文档，基本上就是指技术性的攻略、参考文件，掌握文档的写作方式，就是掌握如何更好地将知识传播，被人所理解使用。

对于作者来说……

最大的头痛，来自于文档需要维护，学习这样的架构可以帮助他们更清晰地了解如何撰写文档，以及应该如何分类，以帮助自己与读者。

对于读者来说……

更清晰地了解在不同的学习阶段获取能够最大效益提升自己知识的方式。

好的文档，四个种类

我认为好的文档就是「留意于目前读者想了解的知识」，放大重点并去除其他的杂讯，详细来说会有哪几种目的的读者呢？

• 学习为主轴 - 想学习某个领域
• 目标为主轴 - 想解决某个问题
• 信息为主轴 - 想获取某些信息
• 理解为主轴 - 想了解某些信息

观察读者的需求，给出对应的解答，依循以上四点的需求，总结出四点可以着重的点，将文档分类为几种类型——

• 教学 - 引导、成就感为重
• 操作 - 目的达成为重
• 参考 - 信息清晰完整为重
• 解释 - 理解思考脉络为重

教学 Tutorial

教学文档应是以引导与成就感为重

教学，让读者能够快速地开始，了解通过教学能达成一些具有成就感、有意义的事情，举例来说：教导一个人如何烘焙。

最终，教会那个人什么并不重要，重要的是这份教学是让人受鼓舞的、感兴趣的、想再去尝试的，是良好的体验，就是好的教学。

教学的过程是有趣的、忽略技术细节的，这类的文章必须避免解释与讨论任何抽象或过于深奥的概念，通常针对特定的领域探讨，从做中学，具备齐发性质。教学是所有文档性质中最困难的，最好的方式，是作为导师尽量与学生（读者）互动。个人认为，在这个阶段 WHY 会大于 HOW，也就是为「为什么要学习 X」会比「要怎么学习 X」还要重要得多，启动学生的学习动机。

• 从做中学（创造知识的垫脚石）
• 从简单的事情开始（并不一定要是最好的范例，但要清晰简白到能让初心者入门，而不是帮助他们到达终点）
• 能立即看见成果（确保每一个动作是微小但可见成效的）
• 提供最低限度完成教学的解释（其余的都会增加分心与困惑）

操作 How-To Guide

操作文档应以达成某种目的为重

操作，展示解决特定问题的流程做法，了解通过阅读就能解决某个问题，或达成某种目的，举例来说：杯子蛋糕的食谱。如果说教学是给初心者的入门指南，那么操作就是给具有一定知识背景的人所提问的解答。就好比有一定基础的甜点师傅，可以依循食谱去制作杯子蛋糕。

过程应是以达成某个特定的目的为主，以目的为导向，这类的文章同样必须避免解释与讨论任何抽象的概念，唯一的重点，就是思考如何尽快简白地达成某个期望的目标。

• 命名很重要（文档的标题应该清晰地表达单一明了的目标）
• 提供一系列的明确步骤（就像教学一样）
• 着重于结果（必须着重于达成某个特定的目标）
• 不要解释概念（如果概念很重要，附注于文档之外）
• 允许灵活性（允许不同的方式去达成同个目标，让学生有想象、自我学习的空间）

参考 Reference

参考文档应以理解思考脉络为重

参考，描述事情的功能性、互动方式，让读者了解到通过阅读就能从中获取想要的信息，举例来说：维基百科。过程应以描述细节信息为导向，因此拥有高度的一致性、语调和文法精确的描述是重要的，严肃且直击重点。

• 格式、语调、保持一致 (就像字典一样)
• 清晰的描述 (解释、讨论、操作、猜测、意见都只会分散注意力)

解释 Explanation

解释文档应以信息清晰完整为重

解释，阐明、分析、明朗化特定的主题，扩张对于某个主题的范围，从不同的角度。举例来说：一本讨论烹饪史的书。使用多种面向去面对一个问题，退后一步去更广阔的了解事情的全貌。解释对于某个主题的看法，供读者通常在闲暇之余去扩充某的主题的知识。

过程应充分给予前后文(Context)并省去步骤与技术细节，并采用多重的范例与假设替代的做法。

• 提供前后文 (解释事情的背景条件和历史，如：设计抉择、技术限制、历史因素)
• 讨论不同的面相和选择 (多种的观点与分析解释)
• 不讨论技术细节与步骤 (这类内容在其他类型的文档中撰写吧)

总结

本篇文章摘取 Daniele Procida🔗 在 Write the Docs EU🔗 和 PyCon Australia🔗 上发表的演说所总结的观点笔记。虽然这样的概念主要还是面向对于程序开发者撰写文档的方式总结，不过我认为同样可以将这样的概念仍适用在各类文档上帮上用场。

资料来源

• The four kinds of documentation, and why you need to understand what they are🔗
• The documentation system🔗