我們的企業為什麼寫不好文檔

昨天早上寫的關於國產數據庫文檔質量太差的文章，實際上是被折騰的沒脾氣後的一種宣泄。我前天下午在分析一個等待事件的時候想起來想看看USTORE的性能，是不是像廠家宣傳的那樣比ASTORE好很多，於是就想找相關的資料看看，找了半天在官方提供的文檔裏就是找不到相關的描述。於是我只能去看數據庫的參數，發現有個和USTORE建表相關的參數，再到百度上去請教了下度娘，找到一篇關於USTORE表創建的文章，照着做後發現使用USTORE後，BENCHMARK不到使用ASTORE的70%，和宣傳的完全不符。於是我想再找找資料，結果一無所獲，於是十分氣憤地宣泄了一番。沒想到這篇文章閲讀量居然超過了2000，看來吐槽的文章遠遠比技術類的文章更受歡迎。

在評論區大家的評論也十分精彩，很多評論都很準確的實施了點穴。寫文檔的不懂技術，懂技術的不屑於寫文檔，這句話總結得相當準確。作為數據庫產品的十分重要的一部分，如果企業真的不把它當成一件重要的事情來做，而是交給公司裏的“低級”職員，甚至實習生來幹，那麼這個數據庫產品在今後確實會“勸退一批數據庫愛好者的”。

實際上一個數據庫的技術文檔，要寫好確實是不容易的，因為數據庫是一個十分龐雜的體系，既要把自己產品的基本概念和原理展現給用户，又不能把公司的核心技術機密透露的太清晰，這本身就不容易。再加上數據庫體系十分複雜，應用場景和優化手段又千差萬別，又要面對技術水平不同用户的不同的需求，確實不容易寫好。我想即使是數據庫產品的產品經理和總架構師都參與其中，也不容易把自己的產品介紹清楚。更何況我們的產品經理和總架構師，總監等高層級的人員是不屑於幹文檔這樣的事情的。這就是我們看到的數據庫文檔質量不高的主要原因。

説數據庫廠商不重視文檔工作可能也不完全準確，不過在文檔開發上投入不足是肯定的。我昨天早上寫文章的時候比較氣憤的是，我一向認為文檔質量還不錯的華為居然能產出如此低質量的文檔。2018年我們的產品開始適配華為OCEANSTOR存儲的時候，覺得華為的文檔質量相當高，通過幾份文檔，我這個以前對存儲完全小白的人也充分了解了華為存儲的總體架構與監控運維的要點。甚至理解了很多華為存儲指標為什麼要這麼設計，它能夠在運維中發揮什麼樣的作用。不僅僅是我，連我們複雜開發這個模塊工具的研發人員，都很快通過文檔熟悉了華為存儲，並在模擬器的幫助下，花了一個月時間就完成了第一個模型版本的開發。

數據庫的文檔只要足夠重視，有足夠的投入就能寫好的嗎？恐怕也不是這麼簡單的。對於寫文檔，我也是深有感觸的。就拿我們自己的文檔來説吧，雖然我十分痛恨文檔寫的不好的廠家，不過我們自己的文檔也沒寫的很好。D-SMART也是一個十分複雜的產品，很多用户使用後都説功能很強大，但是很多功能要摸索很久才能知道藏在哪裏。他們認真閲讀了我們提供的文檔，覺得依然對很多功能瞭解甚少。

當時我們寫這份文檔也費了不少勁，開始是研發部的人寫，總也寫不好，於是我們讓一個使用D-SMART在一線為用户提供服務的DBA重寫了文檔。一線幹活的人寫出來的東西還真的不是蓋的，一下子把兩百多頁的文檔變成了400多頁。內容是極大豐富了，不過裏面大多數是貼圖，文字內容依然質量不高。我當時感覺也沒人能寫了，於是利用空閒時間自己來改這份用户手冊。經過圖片的刪減處理，添加了不少文字，篇幅減少到了300多頁。不過我寫文檔也不專業，於是又把文檔交給售前的同事進行優化。優化後的文檔縮減到了200多頁，不過更為清晰了，大部分圖片也從不負責任的大圖改成了局部小圖，用户反饋也好了很多。這個工作總歷時2年多時間，期間的艱辛也真的只有我們自己能體會到。雖然如此，這份用户手冊的質量依然是不能讓很多用户滿意的。

不過五一後馬上要發佈的2.1版本又面臨一個巨大的問題，菜單重新組織，功能模塊重組，甚至首頁都採用了全新的設計，這些變化也必須體現在文檔中。我前陣子一直和同事們玩命趕研發的進度，對於文檔修改這一塊確實又疏忽了。文檔編制不是一次性的工作，要隨着軟件的升級不斷迭代開發，否則就會與軟件發行版本脱節。我想五一節的時候，我可能也需要花點時間來協助文檔開發人員一起來好好打磨打磨文檔了。

文檔工作量雖大，不過對於一個通用型的軟件產品來説，是必須要做的。否則客户買了你的產品，很多功能不會用，那麼大部分錢花得就冤枉了。實際上文檔工作要做好雖然不易，不過做的認真一點，質量好一點還是有可能的，只要數據庫廠商願意在文檔上進行投入。

數據庫的文檔，我們實際上有很好的老師，Oracle的文檔已經深入人心了，也很適合大部分DBA與數據庫研發人員的閲讀習慣，我們在文檔架構上學習下Oracle的經驗就可以做的很不錯了。

另外一方面就是架構師，產品經理親自參與文檔工作，為文檔架構做出相應的設計，研發人員參與文檔的評審工作，從而發現文檔與產品脱節的問題。文檔開發人員必須有數據庫產品研發經驗的具有數據庫開發背景、具有數據庫運維背景等多方面人員參與。

上面雖然只説了一些簡單的要求，不過這些要求對於數據庫廠商來説，已經很頭痛了，這意味着成本，意味着人才。只有把人才和成本足夠投入了，文檔才能做好。不過作為一個如此重要的基礎設施的原廠，這點投入都投不起的話，那也就是別去搞數據庫產品研發了。