為什麼幾乎所有技術文件讀起來都非常難受？

我們學習一個新接觸的文件時，常常覺得非常難受，而自己消化了再寫教程就非常舒服，這會讓人產生一種錯覺，就是官方文件沒好好寫。

那麼實際上，官方文件為什麼長期以來，難以代替第三方教程的存在呢？

在開源了一系列程式後，除了能力和意願問題外，我發現這個過程中有幾個非常大的影響因素，不親自從事很難意識到，這裡分享一下。

（一）學習者視角

初學者看似啥都不懂，但其實是有一個光環的，就是我看不懂就是順序錯了。而懂了的人如果不是借力求學心路歷程，或者在大量教學中迭代，是非常難做出詳略得當、順序合理的閱讀材料的。

不幸的是，作者剛好是受知識詛咒最深的人。因為讀者一上來看到的就是完整品，會有一個自然發生的概括性認知；但實際上開發它的作者，在心中早已經醞釀過了無數種可能，時間上也曠日持久，早已經難以回憶起這種狀態了，一上來無從說起才是常態。

創作者潛意識中的“常識”，也往往與學習者有很大的差別，因為這正是創作者能無中生有一個作品的原因。從學習者的角度，很容易描述它和以往所有軟體的差異點（如果這是一個好軟體），但對創作者來說，卻並不是這樣，因為他們心中有一個整體性的“事情應該的樣子”，它是一個整體，就是單純覺得現有的工具哪兒都彆扭，而學習者或者宣傳者所說的“本質”，其實從某種意義上講只是“差異點”，只是由於這個差異點本來想不到，現在見識到了，所以印象非常深刻。

（二）功能更新

說白了，一個好的教程的核心，就是一個新接觸者循序漸進展開使用的心路視角。

但是程式總會迭代，不論第一版做得多自洽，有一些看似細節功能的引入，總是會潤物細無聲地慢慢催生出完全並行的不同的使用邏輯和組織思路。

這種情況下寫文件會非常難受，因為新功能會讓舊功能莫名其妙沒有用武之地，而不瞭解舊功能又難以理解新功能究竟為何會長成這樣。這不是增加幾句文件能解決的問題，它需要整體大改、重新寫才有可能改善（類似於程式層面的重構），而這個成本非常大。

本質上，這其實是程式工程本身的微失控，在文件層面的一個反映。

（三）翻譯時的語言障礙

我對翻譯腔是比較敏感和反感的。直到有一次，我自己的文件，先寫了英文，後寫中文，然後我才發現，哪怕是母語，哪怕是原作者自己最知道自己要說啥，在先寫了另一種語言的情況下，都會受到強烈干擾，而有種不會講話了的感覺。

換言之，翻譯的文件不好可能不僅僅是因為具體的語言障礙，導致翻譯者難以明白原文意思，或要翻譯成的語言使用上不地道，而是說不同語言之間本身就有障礙，原作者在頻繁更新軟體、更新測試並更新文件時，還同步更新翻譯的話，語境不知道要切換多少次，其實是非常沉重的負荷。其難度差異類似於，作為程式設計師改兩個bug，和身兼程式設計師與銷售、改bug與接待客戶交替進行之間的差別。

小結：

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

希望我的分享能對即將做這件事的人有所幫助，提前有所準備，或發生後減少困惑的時間。

也希望能有更多人蔘與到這件事裡來，因為不管你是什麼身份，當你覺得奇怪為什麼不做得更好明明很容易時，很可能天時地利人和恰巧你就是最適合幹這件事的那個人。