我的文件之道

文件呀，文件，多少人假汝過時之名行不寫之實？

嗨，你寫文件嗎？
如果是的話，你是怎麼開始的呢？

我記得，我第一次在工作上要寫文件的時候，當時的老闆並不太鼓勵工程師寫文件。

為什麼呢？

可能的理由大概是需要定期更新，而不這樣做的話就變成過時；更糟的也許是誤導或相互衝突的資訊在文件海中造成後人難以下手吧。

那如果是你會直接接受這個答案嗎？

我不太會。
對我來說，把每件事情思考清楚是很重要的。
何況雖然老闆不鼓勵，但他沒有直接反對不是嗎？

我恐怕就是一個想要試探規則邊緣的人。
我當時是這樣想的。

於是我就開始踏上思考之旅，這個題目暫時叫做：文件之於軟體工程的意義。

思考的開始#

首先從關鍵字開始：文件、軟體工程、意義。
其中可以拆成具象與抽象兩組，抽象比較難在初次挖掘，所以先放後面。具象組是「文件」與「軟體工程」，而「軟體工程」是個重要名詞，畢竟同時在我的職銜內，所以先從這裡開始。

什麼是軟體工程呢？你有曾想過這個問題嗎？

在探索的過程中，我讀過一些文件與文章，其中最喜歡的說法來自軟體工程早期的先驅、首先提出 information hiding 的 David Lorge Parnas：

Software engineering is the multi-person development of multi-version programs.

也就是說，軟體工程是多人多版本的程式開發。
這裡的「多人多版本」就算是一人團隊，也會包含過去、未來及現在的自己。

所以軟體工程師的專業，不只是把程式交付開發完成，還包含能在多人多版控的環境下，把這件事做好。

那麼，文件又是什麼呢？

有人說，self-documented code 是軟體工程師的必要技能，也是區分軟體開發者與軟體工程師的一大指標。
但，這還是沒有回答「文件是什麼」。

從日常觀察來看，「文件」有不同的目的與形式，例如 README、API 文件、測試報告、需求規格、架構圖等。內容可能是文字、圖像、表格、流程圖，也可能混合存在。

但從軟體工程的角度看，文件的存在意義與「多人多版本的程式開發」本質密切相關——
在一個會持續演進、持續交接的環境中，文件是穿越人員變動與時間流逝的橋樑。

也許，這就是文件之於軟體工程的意義吧。

從觀念到策略#

洋洋灑灑地分享了我的思考脈絡，不知道你會不會覺得很瑣碎？
但這對我來說，是面對不同問題時，沉澱出思考脈絡的好方法。

雖然我在前一份工作中，透過降低寫作成本與最小化的方式，成功說服老闆不要阻撓我寫文件，但我還是有過不去的地方——我覺得自己還在憑感覺做事。

即使我能 case by case 選擇，也能說服 key person 投資資源，但我是否真的有明確的文件投資策略？
特別是時間有限時，應該如何取捨，才是相對最好的選擇？

因此，在這份工作有機會重新面對「寫文件」的議題時，我想要找到對軟體工程與公司都有價值的選擇。畢竟文件之間還是有權重差別的。我希望除了交付物，這個過程本身對彼此也有意義。

選擇文件的三個評估角度#

我想著，之前老闆的顧慮與現在老闆的不一樣，但大方向還是團隊合作與公司價值。所以我試著用三個方向去思考：

• A: 生命週期
  每份文件的服務時間不同，有些只提供短期專案資訊，有的則會長期存在。這讓我開始用不同角度去看文件維護程度，效期與責任範圍密切相關。

• B: 詢問頻次
  越常被問的問題越值得寫成文件。這不只是節省回應時間，更是知識落差的指標。如果某知識是 single point of failure，就必須水平擴展（horizontal scaling），把知識轉移出去。

• C: 風險程度
  有些資訊雖然少被問到，但一旦出事就難以補救、甚至影響重大。這類文件像逃生手冊，不常用，但用到時一定要能用。

降低寫文件的摩擦力#

解決了「要寫什麼」的問題，接下來是產出策略。
我不希望每次都靠直覺與體力，也不想只有自己會寫。

所以，我借鏡需求開發流程（有 requirement review、design review），嘗試把文件產出也拆解成可協作的過程。

• A: 動筆前，先定義文件的存在意義
  明確讀者是誰、何時會用、要解決什麼任務、技術背景、邊界範圍與不解決的問題。

• B: 從 Outline 開始，找同事 Pair Review
  先交 outline 而不是整包文件，降低修改成本，也避免「文件海壓力」讓人不想看。

• C: 適時剝離細節，避免模糊焦點
  聚焦讀者任務，將額外細節放進 reference 或 FAQ，讓文件保持清晰可讀。

文件的意義#

在降低摩擦力的同時，我發現文件本身不只是結果，撰寫過程更是討論與建立共識的機會。

當大家共同參與 outline 或案例撰寫時，會促成交流與對齊，讓抽象分歧具象化。
文件不只是知識載體，還能推動對話、修正假設、縮小認知落差。

所以，與其說是在產出文件，不如說是透過文件讓團隊的 mental model 互相碰撞，並留下可追蹤的決策歷程。

這正是軟體工程強調版本控制與知識可演進的核心。

回到原點的問題#

嗨，你寫文件嗎？你是怎麼開始的？

我不再只是想知道該不該寫，而是更在意什麼值得寫、怎麼寫才能有意義，並透過過程讓團隊更有方向，讓知識不再只是能者過勞的血淚。

文件之於軟體工程的意義，也許就藏在這些看似瑣碎的選擇中：
選擇留下什麼、為誰留下、用什麼方式留下。
而這些選擇的總和，就是我們如何成為軟體工程師的方式。

沒錯，我也不知道這樣的思考能否引領我成為想要的樣子，更別說是碰到 Staff 的機會。