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

語言: CN / TW / HK

寫文件也是技術活


01:實踐


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

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

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

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

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

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


02:目錄


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

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

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

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

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

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


03:模板


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

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

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

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

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

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


04:內容


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

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

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

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

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

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

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

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


05:工具


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

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

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

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

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

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

END