網際網路公司的技術人，為什麼不寫文檔？

網際網路公司，技術側，寫文檔有沒有必要？

有必要。

要寫什麼文檔？

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

為什麼不寫？

可能是沒時間，可能是不會寫，可能是不願意寫。

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

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

總設和詳設都應該包含的部分：

（1） 需求：一般以産品的語言描述，這一塊可以拷貝産品需求文檔中的story list部分；

（2） 名詞解釋（可選）：非相關領域内的同學需要看到文檔需要提前了解的一些概念性質的東西；

（3） 設計目标：又分為功能目标和性能目标，功能目标一般是對産品需求的技術描述，性能目标是根據産品給出的資料對性能進行的評估。一般來說，新服務必須要有性能目标一項，性能目标可能會影響設計方案。

除了都應該包含的部分，總體設計一般還包含：

（1） 系統架構：一般來說會有個簡單的架構圖，并配以文字對架構進行簡要說明；

（2） 子產品簡介：架構圖中如果有很多子產品，需要對各個子產品的功能進行簡要介紹；

（3） 設計與折衷：設計與折衷是總體設計中最重要的部分；

（4） 潛在風險（可選）；

輸出總體設計的時候，很多方案還是不确定的，故總體設計重點在“方案折衷”，方案需要在設計評審會議上确認。

總體設計評審完畢之後，此時應該是所有方案都确認了，需要輸出各子產品的詳細設計。

詳細設計重點在“詳細”，需要包含：

（1） 總體設計結論彙總（可選）：總體設計上達成一緻的結論有個簡要概述，說明詳設是對這些結論的實作；

（2） 互動流程：簡要的互動可用文字說明，複雜的互動建議使用流程圖，互動圖或其他圖形進行說明；

（3） 資料庫設計：這個是應該放在總設還是詳設呢？

（4） 接口細節：輸入什麼參數，輸出什麼參數，根據接口前端、後端、APP、QA就能夠并行做編碼實作了；

（5） 其他細節：例如公式等；

理論上輸出了詳細設計之後，無論誰拿到了這個詳設文檔，都是能夠完成該項目的。

其他最佳實踐？

一、 大圖

（1） 大系統或複雜流程，其架構圖或者流程圖會非常大，經常比A4紙或word的一頁大很多，此時不宜在word中直接貼圖形，貼了也看不清，建議将圖放在wiki上，文檔中直接貼連結；

（2） 一定要儲存viso或者其他圖形的源檔案，否則今後改動起來要重畫，代價可想而知；

二、 設計與折衷

（1） 設計與折衷是總設中最重要的内容，總設評審中，主要就是讨論這些折衷的優劣；

（2） 評審過後，不但要郵件周知結論，還要在總設中進行更新，說明最終決定使用了哪種方案，為什麼使用這種方案；根據自己的經驗，接手别人的子產品、項目，拿到代碼和文檔，設計方案對我來說完全是個謎！！！

（3） 有時候因為排期或者其他原因，不一定采用了最優的設計方案，此時更應該在總設中記錄決策的過程與原因；

（4） 最後，設計折衷是一個很好的自我辯解的機會：因為項目進度，或者曆史遺留問題，我不得不采取了一個這樣的設計，不要再罵我了。

三、 性能目标

性能目标是新子產品文檔必不可少的一部分，很多項目對性能影響較大的話，也必須撰寫性能目标，性能一般來說可能包含以下部分：

（1） 日平均請求：一般來自産品人員的評估；

（2） 平均QPS：日平均請求 除以 4w秒得出，為什麼是4w秒呢，24小時化為86400秒，取使用者活躍時間為白天算，除2得4w秒；

（3） 峰值QPS：一般可以以QPS的2~4倍計算；

網際網路公司，産品疊代快，可能很多公司沒有“文檔”一說。但其實，寫好文檔，對系統和項目未來的維護是非常有幫助的。

畫外音：文檔清楚，開發階段變化小；未來疊代成本小。

本文轉自“架構師之路”公衆号，58沈劍提供。