How to build a documentation culture in your company
從 0 開始學習技術寫作 #2 - 軟體公司如何在公司內部推行「寫文件」的公司文化
對公司團隊來說，培養「寫文件」文化是非常棒的事情。例如降低新人 onboarding 時的教育成本、跨團隊溝通的時間成本。
但多數的人都覺得「寫文件」是一件麻煩的事情。
如果我們要開始在公司推行「寫文件」文化，應該如何開始呢?以下是來自 Write the Doc 的 6 點建議
從解決 1 個具體的問題開始
從產品/工程團隊開始
收集回饋
先建立文件分類
先建立模版
定期回顧推行成效
1. 從解決 1 個具體的問題開始
「寫文件」是一個很大的目標，對多數沒有習慣的人很難做到。
我們該從小做起，先解決組織中 1 個非常具體的「寫文件」問題。例如:
替「工程團隊」的「A 專案」的「產品」寫文件。
一次只從一個小點做起，就不會勞師動眾、受到大家先入為主的刻板印象。
2. 從產品/工程團隊開始
「寫文件」可以從工程團隊開始。
公司內部的團隊很多，但工程團隊/產品團隊是相對容易獲得「寫文件」的。可以寫的內容包含
專案文件: 例如專案目標、預算、WBS 規劃
流程文件
Code Playbook: 工程師開發的操作指南
Monitoring Information: 監控資訊例如 MIS 人員如何查詢 DB 與 Web Server 的操作文件
最佳實踐: 例如在開發這一段 API 的串接流程時的細節
Style Guides: 例如專案人員在寫 Jira ticket 時的任務格式
3. 收集回饋
讓討論的資訊透明。
管理者雖然希望團隊成員能參加規劃會議
但成員不必都來參加
只要確保討論結果都公開且容易收集到回饋
例如使用 Google Doc 撰寫會議記錄，並讓團隊成員能在有疑問的地方註記。
4. 先建立文件分類
多數公司的文件都是「有機生長 (aka 沒有組織規則)」，這讓其他團隊成員很難維護。
文件維護負責人可以預先建立「分類」，讓成員好整理資料。例如:
Changelog(更新日誌)
開發資源
專案規劃
產品文件
會議記錄
當團隊成員紀錄文件後，按照分類放即可。
5. 先建立模版
建立模版讓同事可以立刻開始。
例如
Jira ticket 模版，只要 3 秒鐘就能有文件大綱可以開始照著指引寫。
會議記錄模版，每個成員都能按照固定格式紀錄
Bug report 模版，讓所有人能一次提供解 Bug 需要的資訊
有一套標準可以遵守時，每個人做事情才會有效率。
6. 定期回顧推行成效
定期回顧「寫文件」的推行狀況。
例如透過 1 周 1 次的公司會議，花 10 分鐘的時間快速走過寫文件進度並收集大家的回饋。
規劃 -> 實行 -> 檢查 -> 修正 -> 回到第一步。
Last updated