为什么开发者的文档总是无法让人满足

知识的传递需要基础

在认知学里面有一个很著名的名字 知识的诅咒(Curse of knowledge)

知识的诅咒（Curse of knowledge）是一种认知偏差，形容专家常以术语交谈，但是丧失与非专业人士沟通的能力。 Robin Hogarth首先提出该名词 。知识的诅咒也是教育的重大阻碍之一。

我更喜欢另外一种说法，当存在信息差的时候，知晓信息多的人是无法将信息完整的传递至其他人的。想想一下，你和你的朋友在玩你画我猜的时候的感觉，就是那种我明明已经画的这么清晰了，为什么你们还是看不出来的憋屈感。

在给同事写的文档中，也如果这般，往往你觉得你需要传递的一切信息都已经摆在那里了，为什么你还是看不懂，这背后的种种原因是因为你觉得看这篇文档的人知识储备是和你一样的，所以你写出的文档往往会成为以信息传递作为目标的通讯稿，就像是执行飞行任务的机长，向地面控制台传递着信息，但是这样的信息往往需要非常统一共识的基础。

举个例子：笔者最近所在阅读的(Envoy-Building)[https://www.envoyproxy.io/docs/envoy/latest/install/building]，这篇文档是在说明安装的过程，然而这背后的信息基础是

• Bazel：一个打包构建工具
• Linux：熟练的Linux命令使用
  当你出现问题的时候，你更需要如何调试 C++ 的基础知识，而这些知识并非是一日之内可以掌握的，因此对于编写文档者，这些隐含的问题应该如何说明，说明到什么程度都是难以量化的。

开发缺乏编纂能力

开发者所擅长的是写博文，针对某一个特定的问题进行分析，一份好的文档可能是不需要整理的，而一份完整的文档是需要分门别类的进行规整的，笔者所在的公司也算是一个在也业内非常爱写文档的公司了，我们的公司文档服务器已经进行过数次的升级了。

公司的文档更像是一个巨大的博客网站，开发者们已经被适应了写一些说明性或者原理性的文档，但是这些文档往往被散落在各处，依赖着不怎么靠谱的内置搜索引擎进行查到，这一切都是非常的痛苦的，且不问大部分的内容都是没有打Tag的，不同的产品之间往往有相似的概念，文档往往又是已项目组分类的，如果你希望找到一篇对于你现在的工作非常有意义的文档，大致上需要经过查询之后点开数个页面再去判断哪些才是你想要的，一点又不高效（但是总比没有的好），当老板在会议上和你要一个东西的说明的时候就发现这个的方式多么的愚蠢。

因此一个好的文档是需要有专业的编纂者的，用户手册部分显然是产品经理更为的适合，而在技术系列中，我认为最好以产品先一个独立的区域，尽可能的带上Tag的方式，零散的存放也可，不过需要注意的是文档一定要注明适用的版本号，当进行过一段时间的开发之后，对于一些明显 OutDate 的文档进行集中的归档。

文档本身也是一种误解

最后也就是一种特别需要小心的现状了，部分开发者希望碎碎叨叨的来描述一些问题，尤其是在一些复杂的问题上，举一个例子：在讲操作系统的时候，我们会涉及到虚拟内存和物理内存的映射，有一些开发者不知道从哪里看来了一个新的名词 线性内存，然后高声阔斧的讲了一大通，然后读者冥思苦想还是不买明白，最终才明白，原来这里说的就是虚拟内存，只不过对于应用来说看起来是一个线性从0增长的概念，对于企业的内部的文档也是如此，尤其在一些老旧的系统中有一些艰深晦涩的概念，这些概念在最初的开发者手中进行了解释，可能解释的并不到位，后续又有千千万万的开发者为此段解释加注解，最终导致内容偏颇，在此笔者还是告诫诸位开发者假如不是很懂的概念的话，切不可望文生义，更不要留下什么著作，在搜索引擎的帮助下，怕不是会带歪诸多人。

尾声

笔者强烈建议将文档要区分为内部文档和外部可见的文档，对于外部可见的文档通过文档审核委员会的同意进行发布，而内部文档建议仅对熟悉项目或相关的人进行开发，也尽可能的避免不相干人的二次创作。内部文档可以简化格式，最为重要的还是内容的时效性和准确性。

愿大家在新的一年里都可以写出好的文档。