最近，公司的重大項目快完工了，除了留下一些Bug，還留下了一些收尾工作，比如我今天要講的文檔。在會上，經理說，怕研發人員寫文檔寫不好。不論經理有沒有說包含激將之意的言語，寫文檔都是一項挑戰性的工作。
文檔開發流程
網上並沒有給出一個比較完美的文檔模板，如何寫這個文檔呢？寫文檔不能簡單的看作寫一篇文章。它也與軟件開發一樣，有一個逐步完善的流程。這是我寫文檔過程中的流程：
圖1 文檔開發流程
1. 確定條件和背景。
在文檔開發的最初階段需要了解文檔寫作的內、外部的條件和背景。不同的專業存在不同的專業背景，對於專業軟件不是按照一個文檔模板，就能把所有的文檔寫出來。
文檔寫作的內部條件：
（1）公司的產品是大型機械設備的狀態監測的軟件，軟件中有許多圖譜和報表，用於顯示狀態監測的數據。軟件的專業性體現在圖譜和報表中，而非軟件的操作當中。
（2） 當前軟件的可運行的版本並不是穩定的版本，寫出來的文檔必須符合穩定版本的軟件的內容。當然存在一種情況，那就是后面的一個版本（也就是正在做的版本）是一個用戶界面比較完善的版本。
開發人員需要對當前軟件所處的狀態做出一些總結，以便在寫文檔時，給自己做出指導。
文檔寫作的外部條件
（1）用戶群體的認識。用戶主要分為幾種：工程人員、銷售人員、專業人士。在這些用戶當中，我們更關注衣食父母-專業人士。對於專業人士，查看圖譜和報表是他們的強項，而他們將面臨的是一個新的軟件，他們需要的是培養一些新的操作習慣。
（2）文檔的最終形式為打印稿。這些專業人士，很多都是經驗豐富的老專家，寫出的文檔需要照顧到老專家們的視覺感受。
這些外部條件是開發人員所容易忽視的，卻是經理們所清晰了解的。在開發之初我的經理們就把這些信息在話語中透露給大家。
了解文檔開發的內、外部條件，能讓我們在文檔開發當中，找到一個大的方向。沒有找到大方向，很容易劍走偏鋒，比如：我花很大的力氣來寫圖譜的內涵，而這是專家所熟知的，到頭來說不定，我寫的有很多錯誤、不夠詳細。
2. 明細要求和准備資源
寫文檔之前，明細各項要求，才能寫出優秀的文檔。什么樣子才能算優秀的文檔呢？這個很難說，但是如果要說你見過哪些狗血的文檔，你可以馬上大量吐槽：
- ·××，居然還有錯別字！
- ·黑壓壓的一片（文字），看都不想看。
- ·啥文檔？找了半天，這個設置功能就是找不到。
- ·我發下這篇文章不適合新手。
細數這些吐槽的片段，作為文檔的作者不得不小心翼翼了。文檔的明細要求來自於文檔的不同的用戶。
經理在文檔出來前，提出的模糊要求：
（1）文檔要符合用戶操作。一般我們閱讀是從左到右，從上到下。
（2）寫出清晰、完整的文檔。
（3）能讓用戶快速入門。
（4）寫出的文檔可操作性要強，不能出現告訴別人一個功能，而他不知道如何才能達到這些效果。
經理在文檔出來后，提出的苛刻要求：
（1）這些文檔格式不統一。重寫！
（2）段落結構混亂。重寫！
（3）歸納的重點偏離。重寫！
測試提出質量要求：
（1）完整性。界面上的功能點，都需要寫出來。不能卻胳膊少腿。
（2）准確性。准確描述功能，給出的步驟能讓測試人員實現，並達到預期的效果。
（3）優美性。格式優美，結構清晰，看上去舒服。
自己的要求
（1）快點寫完這文檔。
（2）寫好點，別讓我重寫，別被吐槽。
用戶的要求
（1）快速了解內容
（2）查看感興趣的部分。
（3）幫助解決問題。
（4）能看懂。
在操刀動筆之前，必須做好准備：
（1）選用一個界面完整的，且不會再做其他修改的軟件版本，作為截圖的來源。
（2） 軟件的數據必須接近真實。
（3）問問工程人員與銷售人員有沒有前一版本的文檔。
3. 提綱。
提綱構築了整個文章的骨架。按照模板寫或者按照前人的模式寫，容易讓文檔缺乏條理。使用提綱，能讓文檔章節分明，結構清晰，內容詳細而充實。下圖即本文該章節的提綱的一部分（該圖使用的軟件是MindManager）：
圖2 提綱
在提綱中划分了章節和細化了一些要點，有了它之后，一篇完整的文章就填滿心中。
4. 編寫與審閱。
第一次編寫是依據提綱來完成的。如果要添加內容，則先在提綱上做出修改，再修改內容。第一次編寫內容，要求做到完美比較難。在寫的過程中會遇到各式各樣的問題，使用Word的批注來記錄面臨的問題，寫完段落回過頭來再修改。
審閱即自己對文檔的測試，查找文檔是否滿足明細的要求，審閱完馬上修改。
編寫文檔過程中重要的一點時，當寫完前面的兩三個章節時，馬上拿給經理（有經驗、了解客戶的、了解業務的經理，如產品經理）看並讓他做出指導。經理手握文檔的生殺大權，同時他會告訴你，他需要什么樣的文檔。如果不這么做，有可能在自己折騰一番之后，重寫文檔。
5. 測試。
在審閱完之后，提交測試。自己的多次審閱會產生精神疲勞，由於心中非常熟悉文章的思路，我們會快速瀏覽文章，而忽略很多不足的和錯誤的地方。我在第一遍之后，測試部測試的結果主要是一些地方寫的不全，一些地方出現了錯別字。
6. 修改與審閱。
面對測試部提出的Bug，做出修改和完善。當然，這次我做出了更加仔細的檢查，以保證無錯別字的情況。
7. 測試、完善並提交。
文檔工作量的划分
寫文檔是一項較為繁重的工作。下面有兩種寫文檔的流程：
第一種是傳統的辦法：
（1）寫整個文檔。
（2）測試。
（3）修改和完善。
這種方法是腦子中默認的流程。但在實際操作的過程中，會出現一些問題：
（1）工作量難以估計。什么時候才能完成這個文檔？經理在問，測試也在問，自己也在問？
（2）其他人無法看到當前的進展。研發、產品、測試經理希望盡早看到成果，哪怕是一部分。每周立會上，整個文檔沒有寫完，研發人員該如何交差？
（3）開發風險大。開發人員不能盡早知道其他人（測試、產品、工程等部門）各項詳細的要求；若寫完整個文檔，被測試部打回來了，全文都得重寫；經過多輪迭代，會浪費研發、測試更多時間，可能會延期提交文檔。
第二種是划分工作量的流程：
（1）寫提綱，並審閱。
（2）根據提綱中的章節划分為多個任務，每個任務走1. 文檔編寫2.提交測試3. 修改完善的流程。
划分工作量的流程相比傳統的流程，有十分明顯的優勢：
（1）在迭代周期內能輸出部分文檔。
（2）任務划分明確，能得到清晰的進展。
（3）降低了文檔開發的質量和時間上的風險。在文檔開發初期，通過經理和測試人員的把關，產出高質量的文檔。
（4）切分了章節的耦合度，讓文章質量更勝一籌。
不足之處：不能完美地解決工作量的問題。