我們如何寫有價值的必要文檔
背景
我入職亞信cboss部門已1年有餘，最大的感受就是每個開發環節都非常注重文檔，軟件或者需求開發的每一步從形式到內容都要求文檔化。這種高度文檔化的模式需要設計者話費大量的精力在文檔的撰寫和維護上、需要投入大量的成本，雖然這種成本在相對固定，變化較少的問題域可以從軟件後期的維護收益上得到補償，實踐中也得到了較好的效果，但是在變化多的問題域，如互聯網、創業企業等，高度文檔化會造成整個軟件生產過程的反應遲滯，進而造成企業競爭力的下降。於是這些要求快速反應，快速更迭的行業逐步放棄了高度文檔化的要求，開始追求原型設計、分步迭代以及代碼文檔。
但是，通過與在互聯網行業工作的朋友交談之後發現，實踐過程中所謂的“敏捷”項目卻從“高度文檔化”走向了“無文檔”：需求也只有幾句定性的描述，一個或幾個開發者自己就鼓搗着把功能完成了，最終交付的也只有一個SVN地址，沒有任何有價值的文檔可言。從結果看，個人認爲這樣的項目是失敗的，無論是技術上還是業務上。個別項目業務需求很大，技術後期滿足不了，只能進行痛苦的重新設計和重寫，這個過程往往耗時甚多，並對業務有或多或少的影響，也就背離了“敏捷”保障業務快速發展的初衷。
作爲開發者，我們的目標是正確認識文檔的作用，制定或運用合適的規範，撰寫必要而足夠的文檔。提升文檔的編寫和閱讀能力，同時使文檔爲我們服務，爲開發和維護過程創造價值。
文檔的作用
既然文檔如此重要，那文檔有具體的哪些作用呢？
幫助設計者克服恐懼
面對新的業務需求，尤其是不熟悉的業務，設計者內心多少會有些忐忑，或者說恐懼。例如前段時間，要我做一個4G轉售優化業務的後臺進程，我從未接觸過這方面的知識，內心難免會有些忐忑，唯恐做出的東西漏洞太多。在新的業務需求全新的設計，需要通盤考慮各種情況如何處理，這個過程中往往還存在很多有牴觸的點，需要設計者取捨。如果不寫文檔，設計者在腦海中構建一個初步的想法之後就會動手編碼。這個初步的想法一般來說都是不全面的，但恐懼往往會驅使程序猿儘快開始行動，試圖看出一些產出，同時也能儘快給管理或者說上層一些相應。可是未經全面考慮的產出往往有着較大的設計漏洞。幸運的情況下這種產出會被後續更改或者覆蓋，如果不幸，這些缺陷的產出會直接把後續的開發帶錯路。
幫助設計者抵禦立即動手編碼的衝動
因爲文檔比代碼的抽象程度更高，寫文檔促使設計者從更加抽象的角度思考問題，藉助文檔的抽象，設計者能從概念而非實現的角度看待整個需求或者系統。脫離了實現細節，設計者更容易發現哪些概念是錯誤的抽象（錯誤抽象是某個概念和其他概念存在不合理的依賴或者交叉）以及整個設計拼圖中有哪些確實。通過撰寫文檔，設計者爲自己提供了一幅圖，從而有勇氣去作全局的設計。
增加溝通和交流
作爲一個團隊成員，我們僅僅交付功能是不夠的，我們交付的是可理解、可維護的功能。爲了這個目標，我們需要和各方進行交流和溝通，把我們的設計思路向他們講清楚。設計評審者通常對項目細節不會非常熟悉，他們關注的是整個項目的核心訴求，技術難點和實現方案是否自洽。他們比設計者（文檔撰寫者）考慮的更加抽象，看的往往是幾張圖或者表格，但這幾張圖和表格並不會憑空出現，一定是從設計文檔中抽象出來的最核心的設計要素。對於服務使用者來說，按照“對接口編程”思想，接口上的文檔通常有兩類，一類是獨立的接口描述文檔和示意圖，這用於團隊內部；另一類是程序內文檔javadoc，作爲接口說明供接口使用者參考。由於javadoc支持html，設計時可以先寫interface，用詳細的javadoc接口描述信息，在用工具抽取成獨立的接口描述文檔。這樣既可以避免兩份文檔之間不一致，也更加容易發現文檔和代碼之間不一致。對服務維護者而言，需要通過詳盡的文檔，才能瞭解最初設計者的意圖，並在後續設計中保持這個意圖。
表明想法和目標
很多時候缺乏文檔是很難了解作者是怎麼想的。如果維護者不知道設計者的思路，再好的設計也無法得到貫徹。如果你是文檔撰寫者，請務必在文檔中說清楚你的想法和目標。
必要的文檔
我們需要文檔，但是不需要冗餘的文檔浪費程序猿的時間和精力。我們希望程序猿寫的每一份文檔都是有價值的，有信息量的。目前來說，對新功能需要提供以下設計文檔。
實體關係圖
包括新功能的用例圖、要引入的實體以及實體之間的關係。實體關係圖的重點是看實體抽象是否正確，新的抽象是否正確實現所有用例。
接口文檔
接口文檔是接口兩端程序猿的約定，任何需要多人合作的邊界上都需要提供接口文檔。接口文檔包括：前後端文檔和後端接口文檔
採用前後端分離的開發模式，前後端接口文檔需要詳細說明列表，每個前後端接口的格式和說明，這個文檔一般由前端提供，後端是吸納。例如：
後端接口文檔，爲了便於同步代碼和文檔，後端接口文檔以javadoc爲主，評審者抽取javadoc即可。Javadoc可以用IDE書寫，更加方便，評審以interface Javadoc爲主。
單元測試，爲每一個新增功能都做好充分的單元測試。單元測試能夠真實的反映出用戶需求和系統API，並能夠幫助程序猿寫出高質量的代碼
系統交互