昨天篇幅好像寫太多了，今天就沒什麼靈感了，大概都被昨天榨乾了，愣是看著電腦螢幕，過了十五分鐘還是沒想法，等等還要去《我或許沒那麼懂 Web》寫關於 Firestore 進階查詢的文章，得趕緊了。看了看昨天寫的文，就挑裡面其中一個議題來寫吧。

文件（Documentation）也是個常常展開爭論的議題。到底該不該寫文件、文件該寫多詳細、文件的定義是什麼、程式碼是不是就可以作為文件、註解算不算文件的一部分、為什麼同事都懶得寫文件、為什麼文件寫好了卻沒幾個同事想看、文件到底該怎麼寫⋯⋯等等，一籮筐的議題可以討論，為之召開一屆鐵人論劍都不為過。

先脫離上面各種各種的問題，回到寫文件的初衷，我想就是「讓別人暸解這個軟體」吧！那麼只要能達成這個目的的事物，應該都算是文件的一種型態，可能是註解、可能是程式碼本身、可能是簡單的 README 文件、可能是比較正式的軟工文件、也有可能是軟體使用者介面上的導引。我認為，只要能幫助我們暸解這個軟體，就可以是文件，包括幫助開發者暸解怎麼使用這個函式庫或套件、包括讓使用者知道怎麼操作、包括讓管理者知道這個軟體的規格和價值是什麼。

而就最傳統的文件，當然莫過寫成文字去描述，可能是 Markdown 格式、也可能是 Office 或其他文書處理軟體的檔案格式。然而多數的程式設計師，對於寫這類文件都感到頭疼，因為去寫文件常常是一個枯燥的過程，且不容易得到回饋，天曉得到底有誰會去看這些文件，多數寫文件都是為了主管而寫，好像寫了文件就不怕有人離職或是相關知識遺失，但為了這類目的寫出來的文件都沒什麼人在看。除了這個問題，這類文件會遇到的另一個問題正如昨天所述，當文件的內容越來越複雜、越來越龐大時，維護的成本就會越高，若是沒有持續關注，可能就會逐漸過期、失效。

所以若是寫給其他開發者看的這類文件、甚至寫給組織內部成員有關這個軟體規格的內容，為了提高程式設計師編寫的動力、讓文件的可用性變高、以及較低的維護成本，最近這類文件都漸漸變成以程式碼或是類似的形式存在。像是「需求實例化」（Specification by Example）就是強調要建立可執行的需求規格、活的說明文件，利用編寫驗收測試（可參考 ATDD）或是編寫描述行為的測試（可參考 BDD），利用測試去作為規格文件與使用文件，讓驗收者可以讀測試裡的描述暸解規格與行為、讓開發者透過測試暸解如何使用等等。

另外，在專案裡建立類似 examples 的目錄，並在下面放置該專案於在各個情境的使用範例，讓開發者去暸解該如何使用，我認為這也是一種文件，而且對於開發者來說，有時候直接讀程式碼會比文字還要來得更快暸解與吸收。

而這類文件形式的好處，正是在其可執行性以及會跟著列入版本控制，一旦可以執行，我們就可以透過其中結果判定這類文件裡面的資訊是否還有效，並可以搭配自動化去隨時驗證，這樣文件的可用性就會持續被維護著。

結果說要論文件，剛講完其中一部分篇幅就差不多了[^1]，所以我才說真的是一籮筐的議題呢。總之，能讓第三者暸解軟體且易於維護的文件，就是好文件。其他的部分，我們之後有機會再聊聊吧！

1: 所以我把標題從原本的「論文件」改成「淺論文件」了。（艸）