程式員，如何寫好文檔？_研發管理

聽說要寫文檔，程式員的第一反應是：為什麼要寫文檔。不寫。程式員的我們善於編碼、善於討論方案、爭辯技術，大多不善於交流、尤其不善於寫文檔。記得我們團隊有的童鞋的周報就一句話：修改bug:TDXXXX,TDXXX2,TDXXX3….
那麼問題就來了，程式要要不要寫文檔。為什麼要寫文檔。如何寫好文檔。 1、文檔有哪些。

溝通紀要、會議紀要、周報、工作總結、需求文檔、總體設計文檔、詳細設計文檔、單元測試文檔、測試案例文檔、需求變更文檔、產品說明書、項目總結文檔等等。
2、寫文檔目的是什麼。

你有沒有遇到過開晨會、周會的時候某個問題已經討論的很清晰。但是幾天后或者臨近周末的時候再說這個問題的時候，團隊中有的童鞋會說：“我不知道，沒有說過這個問題或者這個方案”，因此而造成的BB事很傷神費心。
為了避免出現問題後的瞎BB，特需要形成文字記錄下來。
1）好記憶不如爛筆頭，我們討論很好的方案，有時候只是靈光一閃，儘快記錄下來會留住靈感。
2）追根溯源。口頭開會的時候，大家各抒己見，貌似已經討論出方案。但實際每個人的理解各有不同，會後及時形成文檔甚至圖表，抄收給與會者，便於大家達成共識。如：能清晰界定出責任、明細分工。
3）真正寫的時候，更便於梳理思路。如：需求文檔會清晰定義每一個客戶需求點和要求，是使用者利益保障的前提，是甲方、乙方溝通的紐帶和橋樑。如：會議紀要是大家會議討論結果的總結，存在問題、責任人、解決方案明確的基石。如：變更需求的依據，原來需求怎麼寫的，為什麼不滿足，原因是什麼。如何修改等。 3、文檔的痛點有哪些。

1）認為不重視。程式員往往會感覺沒必要，能技術實現就ok了，其他不重要。
2）真心不想寫。會形成惡性迴圈，這次不想寫，下次、下下次還會如此。
3）感覺沒必要。感覺沒有必要寫，不知道為什麼要寫，不知道寫什麼。 4、文檔的重要性 1）研發開發根據，功能實現根據

需求明細是開發技術實現的依據，驗收時需求矩陣中的每一個點都要覆蓋和完善。 2）關乎項目的持久性。

專案管理中有文檔歸檔管理，規劃、需求、設計等貫穿項目始終的流程中的所有文檔都要歸檔。便於下一個版本或後續項目開展的很好的依據。新加入團隊人員的第一手也是最重要參考文檔。 3）是為證據，便於追責

項目中曾經出現過通過甲方、乙方的郵件作為證據對簿公堂的情況。 3、如何寫好文檔。 3.1提綱挈領

寫之前先列出提綱或者參考公司模板文檔，包含哪幾部分、每個部分的要點是什麼都大致想到。
有了輪廓，再動筆去寫。 3.2邏輯清晰

盡量不要口語化，要邏輯清晰、主次分明。如：周報好的方式包括：
1）上周工作：逐條列出。
2）上周遇到難題：逐條列出。
3) 上周風險點&待討論點：概要列出。（會後討論）
4）本周計劃：逐條列出。 3.3圖文並茂

需要圖、表的地方一定不要省略。比如設計文檔中的：架構圖、模組圖、類圖、活動圖表、流程圖等。
比如設計文檔中的樣本配置.ini、.xml、.conf要以截圖或者表格的形式說明欄位和含義。
一圖勝白文，有圖有真相。 3.4同步更新

這點非常重要。如設計方案真正實現的時候可能和文檔不一致。實現改了，文檔要跟著改。便於自己後續排除問題，也為項目以後的維護者造福。要不別人會看著一頭霧水。
如：代碼更新了，注釋要同步更新。 3.5提供認識

團隊乃至公司上下要形成一致方案，非常重視並上行下效。 3.6全域統籌

剛開始程式員的我們可能不適應，但想到利弊得失。要逐步適應。並且高層要全域統籌，做好相應的獎懲措施，提高大家的認識和積極性。 小結：

文檔並不可怕，想想我們多複雜的架構頭能理順、多邏輯都能實現，文檔也就是小Case。
但是，即便如此，程式員的要非常重視文檔的重要性。

2016-06-19 周日 16:18

作者：銘毅天下
轉載請標明出處，原文地址：http://blog.csdn.net/laoyang360/article/details/51712757
如果感覺本文對您有協助，請點擊‘頂’支援一下，您的支援是我堅持寫作最大的動力，謝謝。