一、實踐
對於多數開發同學來說，很多時候即討厭沒有研發文檔，但是自己又不願意常寫文檔，痛且倔強着。
程序員該不該寫文檔，與爭論哪種編程語言最好一樣，想撕的嘴不留情，該寫的筆不停耕。
當自我的意識上去糾結一件事情要不要去做的時候，不妨停下來看一看，大的職場環境是如何選擇的，糾結自然就沒必要了。
對於寫文檔這件事情，並不需要去思考能帶來哪些好處或者會佔用多少時間，用心去寫自然明白當中利弊。
最近兩年聽到不少搬磚的朋友說，公司已經把文檔管理提升到資產層面，在重大版本推進過程中，預留文檔輸出的時間，這可不是一般的大聰明。
從工作的這幾年實踐經驗來看，寫文檔原則上本着複雜的事項細寫，簡單的事項簡寫或者不寫，卷可以但又不閒的慌。
二、目錄
互聯網的產品，多少存在一定的虛擬屬性，很多事情和想法也都具有明顯的抽象感，如果缺乏文檔的結構化描述，時間拉扯下很容易煙消雲散。
這裏羅列一份在研發管理和職場中，或多或少都會接觸到的文檔內容，雖然結構複雜，但隨着時間的沉澱，其帶來的價值遠大於維護成本。
工作中涉及到的文檔種類比較繁多，但就管理和沉澱的動作來說屬於那種重要但不緊急的事情，這樣說並不是指研發流程中動作的時序可以混亂。
順着工作流程把該輸出的文檔做好，是比較正常的節奏，在特殊情況下也可以先解決事情，再後補文檔。
從開發的角度來說，如果是常規狀態下的版本推進，那麼在版本結束時各種相關文檔就可以上傳指定目錄了。
但是工作中不乏很多生產環境突發的棘手狀況，此時團隊自然優先解決，如果問題影響過大，在事後必然還要輸出總結文檔，即是經驗更是教訓。
三、模板
如果是個人的文檔，簡明扼要即可；但是工作文檔需要有規範和風格上的約束，通常情況下基於統一的模板庫即可。
在研發流程中，通常會圍繞項目的進度管理文檔，在該文檔中會統籌流程中的核心內容，涉及各個階段的進度維護。
基於項目進度管理的文檔模板，在流程推進的過程中，不斷補齊相關的核心內容，清晰準確的記錄版本進度。
採用特定的模板寫工作文檔，本身就會起到規範的效果，在部門的日常管理中，需要階段性的沉澱和維護各類文檔的模板結構，而模板的內容可以根據具體需求來定，在使用的過程中也需要時常優化。
如果文檔模板足夠豐富，在一定程度上可以解決不想寫文檔的問題，在寫文檔這件事上之所以會勸退很多人，很大原因是缺少可用的文檔模板。
當模板庫中存在：項目進度、研發設計、測試用例、階段總結、階段規劃等各種樣例時，下載之後直接使用，編寫核心內容即可，這樣排斥寫文檔的情緒自然減少。
四、內容
文檔的內容是價值所在，對於團隊的協作來說內容簡明扼要即可，讓閱讀文檔的人可以快速準確的理解事情的信息。
通常需要輸出文檔的事項都比較複雜，所以在內容上需要適當的排版，複雜的邏輯儘量使用圖解來描述，這樣內容條理和思路都會很清晰。
對於其他細節方面的把控，比如段落縮進、專業名詞、空格等，通常本着：對內的文檔儘量做好，對外的文檔必須做好的原則。
文檔內容是思考邏輯的呈現，在編寫過程中也容易發現邏輯上的問題，再通過評審討論和完善內容，這樣事情圍繞文檔在後續的過程中不會過度偏離主線。
對於開發這個角色來說，寫文檔是避不開的事，在一個項目上待的時間久了，再看初期的代碼，都覺得不是自己寫的，更別說是複雜的業務邏輯了。
在研發文檔中，最常用的圖解就是邏輯時序，再適當的豐富相關的內容，在一份圖中可以包括流程、邏輯、交互、數據管理等各個核心節點。
開發的設計文檔基本是幾張圖就可以描述清楚的，通常涉及：業務流程圖，邏輯時序圖，數據結構圖。
當複雜的業務呈現在文檔和設計圖上時，其實就是給事情預設好了航線，當然有時候中途被迫返航或變道也不少見。
五、工具
工欲善其事，必先利其器，想快速做好一份文檔，必須得有趁手好用的工具纔行，在多年寫文檔的經驗中，以下工具多少都試用過。
圖中標紅的工具，是個人在實踐中覺得不錯的工具，當下使用最多的是DrawIO和語雀文檔，在免費的邊界內足夠日常使用。
由於工作中需要對接的事項比較多，很難統一協作的各方使用的文檔工具，自然接觸到的工具類型就很複雜，對於團隊內部來說，通常使用辦公軟件集成的工具，以便於統一管理。
寫文檔的習慣已經持續了很多年，工具的變遷也經歷了三次，從辦公文檔遷向Markdown，從線下遷移到線上，更換過一次文檔工具。
時間在變，文檔類產品也在不斷的更新換代，如何尋找自己順手的工具，本着一個基本的原則：免費的範疇內，支持在線管理，功能適當豐富即可。
最後分享一條寫文檔的理由：因爲工作多而複雜，所以要寫到文檔中，這樣便能安心的忘了它。
原文地址：https://mp.weixin.qq.com/s/2PnEhf9ayPiLaVedjH-MEw