最近，公司的重大專案快完工了，除了留下一些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）切分了章節的耦合度，讓文章質量更勝一籌。
不足之處：不能完美地解決工作量的問題。
FastReport使用者手冊（一）文字搜尋
最近開始用fastreport報表，我特將自己使用過程中的一些相關經驗和自己翻譯的官方使用者手冊記錄下來，希望與大家一起學習和使用fastreport報表。歡迎交流！fastreport允許你在預覽視窗中搜尋文字中的一組文字行。通過工具欄上的 按鈕或者ctrl f熱鍵，可執行文字搜尋功能。然後，會出...
聯想智慧型農業移動應用開發系統使用者手冊
1.系統介紹 聯想智慧型農業移動應用開發系統使用者手冊 智慧型農業沙盤。智慧型農業沙盤一端通過com口與智慧型資料閘道器相連，一方面上傳讀取到的感測器資料，另一方面接收來自智慧型資料閘道器的控制命令，控制各報警裝置和控制節點 初始化串列埠讀取和控制api public void initserial...
一文搞定開發學習環境
剛開始學寫 首先要搭建開發環境。新手需要在網上查閱教程，很多時候會遇到各種問題，甚至導致自己的學習進度卡住，學習熱情也因此而減少，這實在是個讓人煩的事情。我們可以簡單分析原因，並慢慢減少此類問題的發生。搭建開發環境經常出錯的原因 1.開發環境不匹配 我們在學習或者實際的開發中，有多種開發平台，比如w...