为什么几乎所有技术文档读起来都非常难受？

我们学习一个新接触的文档时，常常觉得非常难受，而自己消化了再写教程就非常舒服，这会让人产生一种错觉，就是官方文档没好好写。

那么实际上，官方文档为什么长期以来，难以代替第三方教程的存在呢？

在开源了一系列程序后，除了能力和意愿问题外，我发现这个过程中有几个非常大的影响因素，不亲自从事很难意识到，这里分享一下。

（一）学习者视角

初学者看似啥都不懂，但其实是有一个光环的，就是我看不懂就是顺序错了。而懂了的人如果不是借力求学心路历程，或者在大量教学中迭代，是非常难做出详略得当、顺序合理的阅读材料的。

不幸的是，作者刚好是受知识诅咒最深的人。因为读者一上来看到的就是完整品，会有一个自然发生的概括性认知；但实际上开发它的作者，在心中早已经酝酿过了无数种可能，时间上也旷日持久，早已经难以回忆起这种状态了，一上来无从说起才是常态。

创作者潜意识中的“常识”，也往往与学习者有很大的差别，因为这正是创作者能无中生有一个作品的原因。从学习者的角度，很容易描述它和以往所有软件的差异点（如果这是一个好软件），但对创作者来说，却并不是这样，因为他们心中有一个整体性的“事情应该的样子”，它是一个整体，就是单纯觉得现有的工具哪儿都别扭，而学习者或者宣传者所说的“本质”，其实从某种意义上讲只是“差异点”，只是由于这个差异点本来想不到，现在见识到了，所以印象非常深刻。

（二）功能更新

说白了，一个好的教程的核心，就是一个新接触者循序渐进展开使用的心路视角。

但是程序总会迭代，不论第一版做得多自洽，有一些看似细节功能的引入，总是会润物细无声地慢慢催生出完全并行的不同的使用逻辑和组织思路。

这种情况下写文档会非常难受，因为新功能会让旧功能莫名其妙没有用武之地，而不了解旧功能又难以理解新功能究竟为何会长成这样。这不是增加几句文档能解决的问题，它需要整体大改、重新写才有可能改善（类似于程序层面的重构），而这个成本非常大。

本质上，这其实是程序工程本身的微失控，在文档层面的一个反映。

（三）翻译时的语言障碍

我对翻译腔是比较敏感和反感的。直到有一次，我自己的文档，先写了英文，后写中文，然后我才发现，哪怕是母语，哪怕是原作者自己最知道自己要说啥，在先写了另一种语言的情况下，都会受到强烈干扰，而有种不会讲话了的感觉。

换言之，翻译的文档不好可能不仅仅是因为具体的语言障碍，导致翻译者难以明白原文意思，或要翻译成的语言使用上不地道，而是说不同语言之间本身就有障碍，原作者在频繁更新软件、更新测试并更新文档时，还同步更新翻译的话，语境不知道要切换多少次，其实是非常沉重的负荷。其难度差异类似于，作为程序员改两个bug，和身兼程序员与销售、改bug与接待客户交替进行之间的差别。

小结：

以上原因都可能造成原作者哪怕有心又有力，效果却依然比不上第三方出手。

希望我的分享能对即将做这件事的人有所帮助，提前有所准备，或发生后减少困惑的时间。

也希望能有更多人参与到这件事里来，因为不管你是什么身份，当你觉得奇怪为什么不做得更好明明很容易时，很可能天时地利人和恰巧你就是最适合干这件事的那个人。