技術團隊如何維護文件

今天和大家說乙個技術團隊的老問題：乙個長期持續迭代的專案，**已經翻過很多次了，但是技術文件還是最初的樣子，後來的技術人員依靠文件已經無法正確了解專案最初的樣子了。或者是，技術文件寫了很多，但是根本沒人看，不同人寫的文件不夠統一和規範。

在討論解決方案之前，我們首先將技術文件做乙個分類：

1. 對外展示的技術文件，比如tutorial、programming guide。

2. 從**注釋中由軟體生成的，一般是api guide文件。

3. 內部開發資料、參考資料，比如系統設計方案，技術設計方案。

由於第1類文件面對外部客戶，受重視程度自然就高，所以不太存在無法同步更新的問題。

所以，我們今天的討論，主要針對於第3類文件。

在我們日常的工作中，我們做了以下兩件事：

1.通過流程工具將技術文件繫結在團隊的開發活動中。對於乙個模組級的改動，專案管理流程會要求更新文件。對於一些重要專案，要求有文件評審的會議。最後，文件的檢查放在專案發布的 check-list 中。

2. 我們主張用用輕量的wiki 來維護，提供對應的文件模板。一方面不要求工程師提供精美格式的文件，同時讓寫文件盡可能的標準化，降低工程師的心裡負擔。

從理論上說，我們是希望能讓**和文件做到絕對對映，因為這保證了**的改動都能被完整的記錄下來。不過，作為網際網路技術從業者，不可避免的都要面對**改動的高頻發生，投入的時間成本、不同工程師的文字語言統一，都會挑戰文件和**的匹配程度。

所以，我換了一種思路，思考我們團隊到底需要一些什麼技術文件。對每位工程師而言，提高**本身的可讀性，讓**結構更容易理解，比編寫乙份大而全的文件更有價值的事情。換個角度看，作為一名合格的工程師，要掌握前人工作，必須要仔細閱讀**而不是依賴文件來了解系統的細節。

所以，除了我以上提到的2點，我將團隊的技術文件進行了必要的「**」，我們團隊只關注以下三類技術文件：

重要專案技術架構和解決方案（必備的兩個文件：模組的詳細設計和開發設計）

複雜的演算法和資料結構

思維導圖（記錄了會議中的不同角度觀點）

至於我們在每個迭代發生了什麼，依靠jira來詳細記錄，包括對git提交的commit的統一格式要求。

降低了工程師的負擔，同時，如果大家要看過去的文件，內容也非常的有針對性。

所以，文件寫出來，不是為了完成任務，而是凝聚團隊智慧型的瞬間。