這段 隨筆 整理的關於 寫文件常見的問題，寫文件跟寫程式一樣，都是需要訓練的。本文整理的是觀察到普遍的錯誤認知，造成普遍的刻板映像。

問題與現象

不同人看到的問題？

問題從這裡開始：

文件該放哪裡？git？wiki？google drive？ NAS？

這個問題，丟給不同角色，會有不同答案與想像，例如：

寫扣的工程師：

用 markdown 放 git 就好啦 …. (省略三千字)

公司的管理者、主管：

不是放 wiki 就好了，這有什麼好討論的？

一般的業務、行政單位：

行政：wiki 功能太陽春，我們習慣用 office ，放 NAS
業務：要跟客戶一定用 ppt 做簡報功能才夠用

但，我覺得放哪不是主要問題，問題應該改成這樣：

• 文件是給誰看的？誰能看？
• 交付的形式？生命週期 (時效性)？
• 對內還是對外？內部是公司內部？還是組織內部？

文件的核心是給誰看，這個角色是關鍵。

常見的現象

只要談到寫文件，就會有很多抱怨，或者現象，列舉幾個：

1. 文件寫了根本沒人在看
2. 文件與實際的狀況不同步
3. 文件找不到，很亂
4. 文件有很多份，不知道哪一個才是最正確、最新的
5. 文件的負責人不知道是誰？
6. 文件寫再好也沒有價值
7. 沒時間寫文件
8. 敏捷不是說不要寫文件？
9. 文件沒有主要的 TA，用詞亂用、太過複雜、太過精簡 …
10. ….. (省略三千個 …

想想這些現象背後的問題本質是什麼？

刻板映像

文件的刻板映像很多公司都有，但大部分的人無法 體察、意識 到這些問題，更別提如何解決。下面整理的是常見的刻板映像：

• 以為文件不需要管理：文件需要被規範、管理、組織、重構，跟你的程式碼一樣、跟你的房間一樣，久了沒整理就會長蜘蛛網，不知道變數是做啥的，所以房間要定期大掃除，程式碼要定期重構，否則就會有小強在床上爬，技術債讓程式越來越難改。
  • 然後，管理是有成本的。
• 以為買很貴的系統文件就會有結構：以為買了 wiki 文件就會整整齊齊，醒醒吧，用 Virtual Studio 沒有照規矩來，程式碼一樣跟垃圾一樣亂。
  • 不要幻想有 AI 幫你整理文件，AI 知道文件結構，你不知道一樣是垃圾一堆。
  • 很多人靠北 RDBMS 很囉唆，因為要訂 Schema，所以跑去用 NoSQL，從此寫扣飛奔。過兩年後離職，後面接手的人天天問候他老木的老木。
• 普遍的惰性思維：習慣用搜尋找資料：這是 Google 以及 Apple 的 Spotlight 害的，讓普遍的人沒有組織能力。
  • 相關參閱 Spotlight 現象、分類哲學
• 文件寫再好公司也不會賺錢：看企業發展階段來講，到一定規模 (> 100 人)，就必要有全公司的規範與流程。有人生活習慣很好，不煙不酒，一樣突然掛掉，所以我們就天天喝酒抽煙？
  • 很多公司的 API 是產品，但是內部的 API 卻總是亂七八糟。各個團隊協作就是亂七八糟，這樣的產品如何說服客戶？
• 員工天生會寫文件：大家中文都從小學到大，英文也學了十幾年，沒啥道理不會寫作文的。

企業內部文件的管理

意識到問題

在 如何意識到問題的存在 提到一些方法論，重點在於察覺問題，承認問題，面對問題。組織的高層無法觀察到現象、症狀，也無法感知、體察問題，最後承認是個問題，那麼買再好的軟體系統，其實都是沒意義的。

基本原則

簡單整理幾個原則，這些在組織到一定規模之後，是一定要做的：

1. 定義文件的 作業流程 、 管理辦法 、標準用詞。
   • 管理辦法包含交付、時效性、檔案格式、傳遞方式。
2. 文件誰能看？Public / Protected / Private (ACL)
3. 訓練員工 讀 與 寫 文件
   • 從 開會開始：會前準備與會議記錄
4. 建立文件回饋流程
5. 建立共用標準樣板，讓文件正式化

這些事情，有些內部自己要搞定，然後把它落地到系統。制度由內部制定，透過系統軟體，把制度落地。

Connected Mind

這段 Slide 是我在前工作內部教育訓練整理的想法，標題下的是：

Connected Mind

目的是想透過一個方法，讓團隊有效的凝聚共識，共享知識：

整個方法，就是要解決 溝通的原理 提及的，把想說的具象化，然後透過文字做有效的傳遞。

整理這篇文章的時候，剛好有一則新聞：要把人腦植入晶片！馬斯克狂言：人類語言將在5-10年內被淘汰，如果真的實現，那麼人類的溝通將變成傳遞資訊，而這個資訊的呈現形式是什麼？文字，所以文字能力表達不好，傳遞方法再好，也沒用。

趨勢

有一次，跟同事開會，他找不到自己寫的文件，也忘了關鍵字，因為我有大約規範文件的結構，所以依照邏輯，幾秒內就找到了他的文件。還好他有照我的規則放，但他沒有想我的規則。Remote Work 接下來因為武漢肺炎的因素應該會大流行，溝通不再是面對面，而文件會是溝通最好、最有效率的媒介。所以訓練員工閱讀、如何標準化文件格式，將會是趨勢。

現象

以前有一個 Linux 專門的 BBS 站叫做 Sayya，裡面有一位資深前輩 kenduest，他的簽名檔讓我映像很深刻：

現代人普遍的現象

• 小學而大遺
• 捨本而逐末
• 以偏而概全
• 因噎而廢食

我們常常以自己短小的視野看世界，用一單一角度來決定事務的價值。

延伸閱讀

• Spotlight 現象
• 分類哲學
• 溝通的原理
• 如何意識到問題的存在

學習、寫作、閱讀系列文章

• 學習法則
• 一個人的 Working Backwards
• 閱讀能力的重要性
• 為什麼寫文件？
• 再談『為什麼寫文件？』
• 分類的哲學
• Spotlight 現象
• 文件的持續交付
• 寫文件常見的問題
• 從 Jeff Bezos 與 Werner Vogels 學到的
• 導讀持續交付 2.0 - 談當代軟體交付之虛實融合
• 有效定義目標與執行、落地