?1.實踐

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

程序員該不該寫文檔，與爭論哪種編程語言最好一樣，想撕的嘴不留情，該寫的筆不停耕；

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

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

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

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

2.目錄

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

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

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

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

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

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

3.模板

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

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

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

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

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

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

4.內容

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

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

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

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

對于開發這個角色來說，寫文檔是避不開的事，在一個項目上待的時間久了，再看初期的代碼，都覺得不是自己寫的，更別說是復雜的業務邏輯了；

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

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

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

5.工具

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

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

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

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

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

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