好文件的秘訣就是在你寫程式碼的時候就把它寫出來。你是你的第一個聽眾。向自己解釋你在做什麼。未來的你會感謝你自己!

這裡有三個具體步驟，你可以趁早寫好文件。

1. 從準確的筆記開始

當你在程式碼中提出想法時，透過從準確的筆記開始，確保你不會很快忘記重要的細節。雖然你以後會想用長篇的形式向自己解釋一些事情，但短篇的筆記就足以捕捉細節，而不會打斷你的編碼會話流程。

你輸入的終端命令

為什麼您選擇了一種特定的方法而不是另一種方法

您所訪問的連結，以幫助或咳嗽複製-貼上咳嗽的靈感。

你做事情的順序

此時不要擔心完整的句子。只要確保你準確地捕捉上下文，相關的程式碼片段和有用的URL。開啟任何可用的自動儲存選項也會很有幫助。

2. 用詳細的描述解釋決定

做決定很簡單,但是如何做這樣的決定,需要發掘更多的原因和動機,如果你文件寫的更詳細,那麼天長日久之後,你會回憶起當初的設計.

處理這一步的理想時間是當你從編碼中休息的時候，但在你完全出去吃午飯之前，不管你此刻正在做的是什麼。

你要確保當你向自己解釋時，背景、想法和決定都還在腦海裡。

翻閱你所做的短篇筆記，並開始將它們擴充套件為對話式寫作。做你自己的橡皮鴨。描述你正在做的事情，就像你在教別人一樣。你可能會涉及到以下主題。

怪模怪樣的決定。"我通常會這樣做，但我選擇做一些不同的事情，因為..."

您遇到的挑戰以及您如何克服這些挑戰。

支援您專案目標的建築決策

堅持寫要點。長篇大論的寫作並不意味著你會按字數付費! 只要用完整的句子，寫得像向同事解釋你的專案一樣。畢竟你是在向未來的你解釋。

3. 不要忽視先決知識

這一步最好在長時間的午休後，甚至第二天（但可能不是兩天）完成。重新閱讀你的文件，並在你和專案之間保持一定距離後，填補任何變得明顯的空白。

要特別注意填寫或至少連結到先決知識，尤其是當你經常使用不同的語言或工具時。即使是貼上一個你使用的API文件的連結這樣的小動作，也可以節省未來幾個小時的搜尋時間。

寫下或連結到README、安裝步驟和相關支援問題。對於經常執行的命令列操作，你可以使用一個自帶文件的Makefile，以避免每次回到專案時都要處理常見的任務。

即使只是短暫地離開專案，也很容易忘記支援細節。捕捉你這次發現的任何有用的東西。

把所有的事情都記錄下來!

下一次，當你發現自己在想："我肯定會記得這部分的，沒必要寫下來。"只要回憶一下這個表情：♀️。

記得訂正文件的問題,時常勘誤

我讀過很多的文件, 印象最深刻的是文件過期, 跟事實不盡相符, 很多引數,程式碼,都陳舊不堪. 如果你不時常訂正, 那麼你留下來的也不是一個好的文件.

軟體專案是由很多東西組成的，不僅僅是他們的程式碼。為了給未來的自己最好的準備，把所有的東西都記錄下來! 無論是你建立的流程、基礎設施及程式碼，還是曇花一現的未來路線圖想法--把它寫下來! 未來的你會為此感謝你。