程式設計師，如何寫好文件？

聽說要寫文件，程式設計師的第一反應是：為什麼要寫文件？不寫！程式設計師的我們善於編碼、善於討論方案、爭辯技術，大多不善於交流、尤其不善於寫文件。記得我們團隊有的童鞋的週報就一句話：修改bug:td***x,td***2,td***3….

那麼問題就來了，程式要要不要寫文件？為什麼要寫文件？如何寫好文件。

溝通紀要、會議紀要、週報、工作總結、需求文件、總體設計文件、詳細設計文件、單元測試文件、測試用例文件、需求變更文件、產品說明書、專案總結文件等等。

你有沒有遇到過開晨會、週會的時候某個問題已經討論的很清晰。但是幾天後或者臨近週末的時候再說這個問題的時候，團隊中有的童鞋會說：「我不知道，沒有說過這個問題或者這個方案」，因此而造成的bb事很傷神費心。

為了避免出現問題後的瞎bb，特需要形成文字記錄下來。

1）好記憶不如爛筆頭，我們討論很好的方案，有時候只是靈光一閃，盡快記錄下來會留住靈感。

2）追根溯源。口頭開會的時候，大家各抒己見，貌似已經討論出方案。但實際每個人的理解各有不同，會後及時形成文件甚至圖表，抄收給與會者，便於大家達成共識。如：能清晰界定出責任、明細分工。

3）真正寫的時候，更便於梳理思路。如：需求文件會清晰定義每乙個客戶需求點和要求，是使用者利益保障的前提，是甲方、乙方溝通的紐帶和橋梁。如：會議紀要是大家會議討論結果的總結，存在問題、責任人、解決方案明確的基石。如：變更需求的依據，原來需求怎麼寫的，為什麼不滿足，原因是什麼？如何修改等。

1）認為不重視。程式設計師往往會感覺沒必要，能技術實現就ok了，其他不重要。

2）真心不想寫。會形成惡性迴圈，這次不想寫，下次、下下次還會如此。

3）感覺沒必要。感覺沒有必要寫，不知道為什麼要寫，不知道寫什麼？

需求明細是開發技術實現的依據，驗收時需求矩陣中的每乙個點都要覆蓋和完善。

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

專案中曾經出現過通過甲方、乙方的郵件作為證據對簿公堂的情況。

寫之前先列出提綱或者參考公司模板文件，包含哪幾部分、每個部分的要點是什麼都大致想到。

有了輪廓，再動筆去寫。

盡量不要口語化，要邏輯清晰、主次分明。如：週報好的方式包括：

1）上週工作：逐條列出。

2）上週遇到難題：逐條列出。

3) 上週風險點&待討論點：概要列出。（會後討論）

4）本週計畫：逐條列出。

需要圖、表的地方一定不要省略。比如設計文件中的：架構圖、模組圖、類圖、活**、流程圖等。

比如設計文件中的示例配置.ini、.xml、.conf要以截圖或者**的形式說明欄位和含義。

一圖勝白文，有圖有真相。

這點非常重要。如設計方案真正實現的時候可能和文件不一致。實現改了，文件要跟著改。便於自己後續排除問題，也為專案以後的維護者造福。要不別人會看著一頭霧水。

如：**更新了，注釋要同步更新。

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

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

文件並不可怕，想想我們多複雜的架構頭能理順、多邏輯都能實現，文件也就是小case。

但是，即便如此，程式設計師的要非常重視文件的重要性。