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