寫文件常見的問題


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


問題與現象

不同人看到的問題?

問題從這裡開始:

文件該放哪裡?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 害的,讓普遍的人沒有組織能力。
  • 文件寫再好公司也不會賺錢:看企業發展階段來講,到一定規模 (> 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,他的簽名檔讓我映像很深刻:

現代人普遍的現象

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

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


延伸閱讀

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



Comments

  • 全站索引
  • 關於這裏
  • 關於作者
  • 學習法則
  • 思考本質
  • 一些領悟
  • 分類哲學
  • ▲ TOP ▲