剛開始工作的時候，總覺得寫文件很麻煩，程式寫完，會動、執行結果正確不就沒事了嗎，為什麼要寫一堆惱人的文件或註解，麻煩死了，自己寫的東西怎麼可能會忘記？
結果過了一陣子回來看自己半年前寫的東西，有些還真的不知道發生什麼事了，完全沒印象當初怎麼會這樣寫，或者是有些操作流程忘記了，導致沒辦法正常執行某些程序。
這個時候才後悔當初自己為什麼沒有留下一些文件可以參考。
總之，要寫文件，還要有一些方向，這篇主要就是想要聊一下兩件事，一、寫文件的目的跟好處，二、怎樣的內容需要文件化。
寫文件的目的跟好處
溫故知新
在寫文件的時候，通常就是把自己做過的事情，再用文字的方式陳述、紀錄一次，因此在撰寫的當下，就是一種複習及思緒的釐清。
在撰寫文件的時候，常常會突然有一些想法，像是：「這邊好像可以用別的方法做」、「這樣做好像有什麼缺點」，所以在撰寫的過程中，就是一種複習與檢討（凌虐大腦？）。
再來，為了讓東西文件化，自然也會希望寫出來的東西，自己以後看得懂，所以會想辦法釐清思緒，把想法、跟概念，用完整、結構化的方式呈現，這就是一種思緒的釐清。
救人救己
有時候過了一陣子，回頭看某些東西，即便程式碼寫得再好，架構設計的多好、可讀性有多高，還是需要花一點時間理解。但如果有良好的文件，大概快速瀏覽過文件後，就可以快速回覆記憶，想起這段程式或流程的概念。
或是有時候要將過去的工作交接給別人，自己還是要花大量時間去複習，才能避免漏掉一些重要資訊。此外，認真交接的過程通常費時費力，因此很多人都草草了事（尤其是要離職的人XD)，導致重要資訊流失，對於被交接的人來說，也是一種苦難。若是有良好的文件，可以直接把文件交給對方，有效減輕交接的成本跟提高資訊保留度。
怎樣的內容需要文件化
一提到寫文件，大家會覺得厭煩的原因通常是，不知道要記錄什麼內容，寫到最後會變成很像流水帳，有意義的內容只佔一小部分，卻要花費大量時間，然後老闆還在那邊催進度，於是就放棄寫文件了。
所以當然不可能什麼都記，要怎麼維護那麼大量的文件是一個問題，寫文件花費的大量時間也是一個問題，不可能讓寫文件反客為主，畢竟開發才是主要目的。
那到底要紀錄什麼？我想我就以「工程師」的角度出發，來聊一下哪些內容需要文件化。
一定要文件化的部分
怎樣的內容一定要寫文件保留？我覺得就是一些如果忘記了，很難、甚至無法透過閱讀程式本身而找回記憶的東西。它就會變成一個黑盒子，沒有人知道為什麼這樣（失傳的上古技藝？），對於日後的開發一定會造成很大的困擾。
奇怪的商業邏輯
老闆常會有一些天馬行空的想法，或是為了配合現實考量，會需要有應急的做法，很可能會破壞原本正常程式架構、流程。這種東西可能過一陣子沒人知道為這段程式、做法到底是為什麼而存在的，會不知道怎麼處理。
特殊的程式用法
有一些程式用法是比較少見或是不直觀的，那通常會這樣做會有一些特殊的理由，像是內建的函式可能沒辦法處理某些特殊情況，所以要自己另外實作，或是為了要繞過某些bug，而必須用非常奇怪的方式實作。
不熟悉的設置流程
通常是機器的設定，像是開發環境的設定、或是正式環境的設置、或是其他周邊服務，像是快取，訊息佇列等。雖然現在有docker的協助方便了很多，可是因為更改機器配置的頻率不高，下次要調整的時候，很有可能會忘記前一次有做過什麼特殊處理，尤其是每家公司的系統需要客製化的部分都不太一樣，最好還是特別紀錄一下。
最好文件化的部分
再來是，我覺得最好有文件的部分。這邊主要是幫助快速恢復記憶以及避免犯錯。
中大型程式架構、模組
比較大型的模組、架構，可能會關聯到很多類別。可以記錄一下設計的想法、模組中主要元件的互動方式等等，或是模組的使用方法等，讓用的人以及日後維護的人有跡可循。
較複雜的商業流程
有些商業流程可能比較複雜，資料流動、處理的方式會經過很多步驟。最好可以把步驟或特別需要注意的部分記錄下來，日後處理的時候，才不會漏掉某些地方或做錯。
決策過程、討論過程
做法經常是討論出來的，可以把討論過程中提到的優劣分析、或是困難及限制記錄下來，供以後參考。
不需要寫文件的部分
即便寫文件很重要，但寫文件畢竟還是很惱人的，所以最好可以減少文件的量。
那要怎麼達到呢？其實就是老生常談：「可讀性」。回想前面提到的關於寫文件的好處，大部分都是幫助理解程式運作，如果說，程式本身就能交代得很清楚，那自然就不需要額外的文件了。
雖然這個分寸有點難以拿捏，有些時候可讀性高的程式，可能因其複雜性過高，還是需要文件的補助，但至少，簡單的程式，可以透過高可讀性，避開瑣碎的文件。
結論
寫了一陣子文件，還是覺得寫文件很麻煩，但是回頭想一下寫文件的好處，就覺得還是多少寫一下吧，大概就像是寫自動測試一樣，是短期內看不到好處的行為，必須要把時間尺度拉長，才能感受得到。
不過換個角度用積極一點的方式看待，也算是記錄自己工作的歷程，跟一種經驗的累積與傳承吧。