研發過程中的文件管理與工具

寫文件也是技術活

01：實踐

對於多數開發同學來說，很多時候即討厭沒有研發文件，但是自己又不願意常寫文件，痛且倔強著；

程式設計師該不該寫文件，與爭論哪種程式語言最好一樣，想撕的嘴不留情，該寫的筆不停耕；

當自我的意識上去糾結一件事情要不要去做的時候，不妨停下來看一看，大的職場環境是如何選擇的，糾結自然就沒必要了；

對於寫文件這件事情，並不需要去思考能帶來哪些好處或者會佔用多少時間，用心去寫自然明白當中利弊；

最近兩年聽到不少搬磚的朋友說，公司已經把文件管理提升到資產層面，在重大版本推進過程中，預留文件輸出的時間，這可不是一般的大聰明；

從工作的這幾年實踐經驗來看，寫文件原則上本著複雜的事項細寫，簡單的事項簡寫或者不寫，卷可以但又不閒的慌；

02：目錄

網際網路的產品，多少存在一定的虛擬屬性，很多事情和想法也都具有明顯的抽象感，如果缺乏文件的結構化描述，時間拉扯下很容易煙消雲散；

這裡羅列一份在研發管理和職場中，或多或少都會接觸到的文件內容，雖然結構複雜，但隨著時間的沉澱，其帶來的價值遠大於維護成本；

工作中涉及到的文件種類比較繁多，但就管理和沉澱的動作來說屬於那種重要但不緊急的事情，這樣說並不是指研發流程中動作的時序可以混亂；

順著工作流程把該輸出的文件做好，是比較正常的節奏，在特殊情況下也可以先解決事情，再後補文件；

從開發的角度來說，如果是常規狀態下的版本推進，那麼在版本結束時各種相關文件就可以上傳指定目錄了；

但是工作中不乏很多生產環境突發的棘手狀況，此時團隊自然優先解決，如果問題影響過大，在事後必然還要輸出總結文件，即是經驗更是教訓；

03：模板

如果是個人的文件，簡明扼要即可；但是工作文件需要有規範和風格上的約束，通常情況下基於統一的模板庫即可；

在研發流程中，通常會圍繞專案的進度管理文件，在該文件中會統籌流程中的核心內容，涉及各個階段的進度維護；

基於專案進度管理的文件模板，在流程推進的過程中，不斷補齊相關的核心內容，清晰準確的記錄版本進度；

採用特定的模板寫工作文件，本身就會起到規範的效果，在部門的日常管理中，需要階段性的沉澱和維護各類文件的模板結構，而模板的內容可以根據具體需求來定，在使用的過程中也需要時常最佳化；

如果文件模板足夠豐富，在一定程度上可以解決不想寫文件的問題，在寫文件這件事上之所以會勸退很多人，很大原因是缺少可用的文件模板；

當模板庫中存在：專案進度、研發設計、測試用例、階段總結、階段規劃等各種樣例時，下載之後直接使用，編寫核心內容即可，這樣排斥寫文件的情緒自然減少；

04：內容

文件的內容是價值所在，對於團隊的協作來說內容簡明扼要即可，讓閱讀文件的人可以快速準確的理解事情的資訊；

通常需要輸出文件的事項都比較複雜，所以在內容上需要適當的排版，複雜的邏輯儘量使用圖解來描述，這樣內容條理和思路都會很清晰；

對於其他細節方面的把控，比如段落縮排、專業名詞、空格等，通常本著：對內的文件儘量做好，對外的文件必須做好的原則；

文件內容是思考邏輯的呈現，在編寫過程中也容易發現邏輯上的問題，再透過評審討論和完善內容，這樣事情圍繞文件在後續的過程中不會過度偏離主線；

對於開發這個角色來說，寫文件是避不開的事，在一個專案上待的時間久了，再看初期的程式碼，都覺得不是自己寫的，更別說是複雜的業務邏輯了；

在研發文件中，最常用的圖解就是邏輯時序，再適當的豐富相關的內容，在一份圖中可以包括流程、邏輯、互動、資料管理等各個核心節點；

開發的設計文件基本是幾張圖就可以描述清楚的，通常涉及：業務流程圖，邏輯時序圖，資料結構圖；

當複雜的業務呈現在文件和設計圖上時，其實就是給事情預設好了航線，當然有時候中途被迫返航或變道也不少見；

05：工具

工欲善其事，必先利其器，想快速做好一份文件，必須得有趁手好用的工具才行，在多年寫文件的經驗中，以下工具多少都試用過；

圖中標紅的工具，是個人在實踐中覺得不錯的工具，當下使用最多的是DrawIO和語雀文件，在免費的邊界內足夠日常使用；

由於工作中需要對接的事項比較多，很難統一協作的各方使用的文件工具，自然接觸到的工具型別就很複雜，對於團隊內部來說，通常使用辦公軟體整合的工具，以便於統一管理；

寫文件的習慣已經持續了很多年，工具的變遷也經歷了三次，從辦公文件遷向Markdown，從線下遷移到線上，更換過一次文件工具；

時間在變，文件類產品也在不斷的更新換代，如何尋找自己順手的工具，本著一個基本的原則：免費的範疇內，支援線上管理，功能適當豐富即可；

最後分享一條寫文件的理由：因為工作多而複雜，所以要寫到文件中，這樣便能安心的忘了它。

END