關於程式設計師寫文件（網路轉載）

      提到寫文件，你的反應是什麼？

      寫文件，本來在碼農眼中就不是什麼分內之事。真要到了趕鴨子上架的份上，碼農的各種不良反應也都來了，有的人心慌、沒底；有的人心不甘、情不願；也有的人渾身發怵心有餘悸。
      不同的不良反應都折射出各色碼農對於寫文件的態度。

• 心慌沒底的應該是沒有寫過文件，在偌大的一張A4紙或是一頁word文件上，他們能夠發呆老半天，就是無從下筆，不止從何寫起。他們很難有層次的、有重點的讓別人明白文件想要傳達的意圖，也有可能他們自己也不知道要傳達什麼。

• 心不甘情不願的多多少少會有點文件無用論的想法，認為文件沒什麼用。遇到需求來了，就開始拿起鍵盤，一通複製貼上，洋洋灑灑的就可以碼起了自己的專案，又何須多一道寫文件這種“中看不中用”的手續。

• 渾身發怵心有餘悸的應該是寫過文旦並且在文件上栽過跟頭的，他們認識到文件的重要性和作用，但是因為文件沒有寫好，比如疏漏了某個點最終導致開發偏離正軌，這樣的經歷和慘痛教訓仍歷歷在目。

  
  

      最近自己寫一個小專案的開發文件過程中遇到不少問題，也從老大那邊學到了不少經驗，所以在此總結下。

---

      寫文件，我們會遇到什麼問題

      作為碼農，毫無疑問，我們的第一使命就是撲上前線寫程式碼，我們常常沉浸在自己的技術世界中無法自拔。一個問題，一個需求出來，我們本能的在腦海中閃過出各種演算法、各種設計模式、各種架構，設想了各種讓人眼花繚亂的技術解決方案。但是，我們很少從另外一個角度來看待問題以及解決問題——業務角度。我們很少問自己為什麼會出這個bug，我們從業務上有沒有必要這麼做，當初的設計是否考慮周全？

      文件的重要性，其實大家應該都很清楚。一份好的文件，可以大大減少溝通成本，開發成本，尤其在專案涉及到多個專案組合作的時候，有一個標準文件顯得格外重要。同時，有了文件，也方便日後的同事快速熟悉業務。文件固然重要，但是寫起來並不簡單！我們很容易遇到這些問題：

• 思維定式
  長時間奮鬥在一線的我們在寫起文件時容易思維定式，條件反射的從技術實現角度來考慮問題，容易鑽牛角尖。最終寫出來的文件可能因為技術性太強，所以一起參與開發的其他組或者非技術人員會就很難讀懂。

• 格局小
  因為我們對於自己相關負責的模組會比較熟悉清晰，自然寫的比較詳細。而對於其他專案組以及相關人員的工作職責不清楚，就寫的比較模糊。後面別人看文件時因為疑問較多，需要反覆的溝通確認，這樣就增加了時間和人力的成本。或者別人索性也不問，直接在模糊的文件基礎上加入自己的理解，這樣就可能誤解了原來的設計需求，導致做了一些無用的開發，間接導致專案延期。

  
  

      所以，我們應該走出自己的一畝三分地，走出自己的小天地，站在一個高點，有一個全域性觀。從全域性角度，讓整個設計方案在理論上和實際溝通後確實可行。對於每個部分，尤其是各專案組或者各部門的銜接部分要反覆確認，減少後期不必要的對接成本。具體，我們可以從下面一些點著手。

---

      為了寫好文件，我們該怎麼做開會不是走形式

      大部分人對開會都沒有什麼好感，我們參加過太多又臭又長而又漫無目的的會議，這些形式主義的會議耗去了我們太多的精力和耐心。但是，不可否認，會議本身沒有錯，只是有些人沒有用對而已。
      當然有些問題和議案我們大可不必通過會議的形式來討論解決，我們可以直接找到相關的人來一場face to face的高效溝通。但是會議本身有一些不可替代的好處：

• 集思廣益
  因為有些專案需要很多人、多個專案組參與開發，對於一個需求，某個人的瞭解比較片面，通過會議的形式，大家都能出謀劃策，利用自己的技術和業務背景知識獻計獻策，讓文件、方案考慮更加周全。

• 儀式感
  就像老大說的，通過會議的形式營造出一種儀式感。大家通過一個很正式的會議形式明確自己的職責並對要做的工作做好安排，這無形中增加了大家各自心中的責任感。

  
  

      基於此，會議有其必要性。在開會這件事上，我們還有幾個注意的點。

• 開會前，先知會需要參會的人員，確保大家都能就位。

• 開會前，提綱挈領的列出此次開會著重要討論的問題，針對問題來開會，提供開會的效率。如果在開會的時候才想著要討論的問題，就會目的性不強，可能聊著聊著就跑偏了。

• 做好會議摘要，針對會議中提到的問題以及解決方案，簡要記錄，會後整理到文件中。

• 開會時，自己的立場要堅定，對於明確確定的要求不能動搖或者模稜兩可。當然，這不是說要在開會偏執己見，不管別人說的對與錯都不辨是非還固守自己的觀點。

  
  

      積極推動、及時跟進

• 對於牽頭專案的人在跳脫自己一畝三分地的思想之外，我們還應該保持積極推動和跟進的熱情。

• 對於一些模糊的點需要找相應的人反覆確認，對於大家有歧義的地方不要支支吾吾，敷衍了事，因為這樣很有可能就會偏離設計需求的初衷。

• 作為碼農，一般喜歡跟程式碼打交道，不大願意也不太擅長於人溝通打交道，但是為了明確自己做的或有意義，我們需要積極主動的溝通。因為花點時間溝通明確了問題和需求，要好過我們因為沒有弄懂需求而反覆修改程式碼，最後讓自己疲憊又被動。

• 對於設計文件的整個邏輯要清楚，先保證設計能通，然後在每個部分考慮具體細節，不要只相信某一個人的說法。比如A說不需要B的參與我們就能搞定問題，但是等最終做完發現，因為沒有B的參與，系統根本不可能用。我們需要自己想清楚，並找可能與之有關的人員核實清楚。

  
  

      寫文件並不那麼簡單，看似單薄的幾頁文件需要我們有嚴密的邏輯，能夠協調和把控各個環節，跟蹤和調整專案的進度，只有這樣才能體現文件的重要性併發揮它的價值。