互聯網公司的技術人，爲何不寫文檔？

互聯網公司，技術側，寫文檔有沒有必要？

有必要。

要寫什麼文檔？

至少要寫整體設計文檔，詳細設計文檔。

爲何不寫？

多是沒時間，多是不會寫，多是不肯意寫。

本文試圖分享一些經驗，解決「不會寫」的問題。

整體設計文檔，詳細設計文檔，應該包含什麼內容？

總設和詳設都應該包含的部分：
（1） 需求：通常以產品的語言描述，這一塊能夠拷貝產品需求文檔中的story list部分；
（2） 名詞解釋（可選）：非相關領域內的同窗須要看到文檔須要提早了解的一些概念性質的東西；
（3） 設計目標：又分爲功能目標和性能目標，功能目標通常是對產品需求的技術描述，性能目標是根據產品給出的數據對性能進行的評估。通常來講，新服務必需要有性能目標一項，性能目標可能會影響設計方案。

除了都應該包含的部分，整體設計通常還包含：
（1） 系統架構：通常來講會有個簡單的架構圖，並配以文字對架構進行簡要說明；
（2） 模塊簡介：架構圖中若是有不少模塊，須要對各個模塊的功能進行簡要介紹；
（3） 設計與折衷：設計與折衷是整體設計中最重要的部分；
（4） 潛在風險（可選）；

輸出整體設計的時候，不少方案仍是不肯定的，故整體設計重點在「方案折衷」，方案須要在設計評審會議上確認。

整體設計評審完畢以後，此時應該是全部方案都確認了，須要輸出各模塊的詳細設計。

詳細設計重點在「詳細」，須要包含：
（1） 整體設計結論彙總（可選）：整體設計上達成一致的結論有個簡要概述，說明詳設是對這些結論的實現；
（2） 交互流程：簡要的交互可用文字說明，複雜的交互建議使用流程圖，交互圖或其餘圖形進行說明；
（3） 數據庫設計：這個是應該放在總設仍是詳設呢？
（4） 接口細節：輸入什麼參數，輸出什麼參數，根據接口前端、後端、APP、QA就可以並行作編碼實現了；
（5） 其餘細節：例如公式等；

理論上輸出了詳細設計以後，不管誰拿到了這個詳設文檔，都是可以完成該項目的。

其餘最佳實踐？

1、 大圖

（1） 大系統或複雜流程，其架構圖或者流程圖會很是大，常常比A4紙或word的一頁大不少，此時不宜在word中直接貼圖形，貼了也看不清，建議將圖放在wiki上，文檔中直接貼連接；
（2） 必定要保存viso或者其餘圖形的源文件，不然從此改動起來要重畫，代價可想而知；

2、 設計與折衷

（1） 設計與折衷是總設中最重要的內容，總設評審中，主要就是討論這些折衷的優劣；
（2） 評審事後，不但要郵件周知結論，還要在總設中進行更新，說明最終決定使用了哪一種方案，爲何使用這種方案；根據本身的經驗，接手別人的模塊、項目，拿到代碼和文檔，設計方案對我來講徹底是個謎！！！
（3） 有時候由於排期或者其餘緣由，不必定採用了最優的設計方案，此時更應該在總設中記錄決策的過程與緣由；
（4） 最後，設計折衷是一個很好的自我辯解的機會：由於項目進度，或者歷史遺留問題，我不得不採起了一個這樣的設計，不要再罵我了。

3、 性能目標

性能目標是新模塊文檔必不可少的一部分，不少項目對性能影響較大的話，也必須撰寫性能目標，性能通常來講可能包含如下部分：
（1） 日平均請求：通常來自產品人員的評估；
（2） 平均QPS：日平均請求 除以 4w秒得出，爲何是4w秒呢，24小時化爲86400秒，取用戶活躍時間爲白天算，除2得4w秒；
（3） 峯值QPS：通常能夠以QPS的2~4倍計算；
畫外音：詳見《架構，如何進行容量設計？》。

互聯網公司，產品迭代快，可能不少公司沒有「文檔」一說。但其實，寫好文檔，對系統和項目將來的維護是很是有幫助的。
畫外音：文檔清楚，開發階段變化小；將來迭代成本小。

架構師之路-分享可落地技術

相關推薦：

《回表查詢？索引覆蓋？| 1分鐘系列》新出爐
《優化工具，迅猛定位低效SQL | 1分鐘系列》
《數據庫容許空值(null)是悲劇的開始 | 1分鐘系列》
《兩類很是隱蔽的全表掃描 | 1分鐘系列》

大家公司寫設計文檔麼？