如何寫好技術文件？給作為軟件工程師的你，寫出容易明白的文件
作為軟件工程師的你，寫出來的技術文件經常被客戶投訴「看不懂」是常有的事。
那麼，為什麼我們寫的技術文件會那麼難懂？
我想，這是因為你的文件和讀者的需求錯配了。
The Documentation System 指出，技術文件有四種，各自對應有不同需求的讀者：
- 新手教學：給第一次接觸這個系統的人。
- 操作指南：給想要用這個系統解決問題的人。
- 概念解釋：給想了解這個系統如何運作和背後原理的人。
- 參考文件：給對這統很熟悉的資深用家。
一份好的技術文件應該也有以上四種文件。
新手教學
新手教學指的是對用家來說第一份用來上手做到第一件事的文件。寫這種文件時要注意：
- 步驟要十分詳細：用家在沒有任何背景知識下，只要跟著你的步驟做，就能夠做到你想他做到的事。
- 你定義用家能夠跟著這份文件後能夠完成什麼，在這份文件中不用理會用家的需求。
- 不要在這份文件中解釋專有名詞：這份文件只是起手用，用家跟著這份文件完成後對你的系統有一點印象和有一點成就感已經足夠。
操作指南
操作指南指的是用家對你的系統有一點點認識後，對於一些很常用這個系統能夠做到的事的步驟說明書。寫這種文件時要注意：
- 要寫詳細的步驟和用家在跟著這些步驟時如果遇到問題的解決方案。
- 一份文件對應一個解決的問題。
- 不要在這份文化中解釋背後的原理：有一些用家用你的系統只是為了解決問題，他們不會在意背後的原理。
- 如果真的很想想用家理解背後的原理，那麼可以把概念解釋文件的連結放在這裡給參考（概念解釋文件在下文會介紹）。
- 文件標題是「如何 XXX？」
概念解釋
概念解釋是解釋你的系統如何運作的文件。讀者對你的系統有大概印象後，他們也許對這個系統的內部有興趣：
- 這份文件不會有件何指作步驟，只有如何運作等的概念解釋。
- 文件標題用名詞開始，或是用問句，例如是「為什麼 XXX？」
- 解釋時盡量加入一些上文下理幫助讀者理解。
- 解釋時可以加入一些例子、比喻 或 圖像來幫助解釋。
參考文件
參考文件是讀者對系統如何運行有一定概念後，他們也許需要用這做系統做出更客製化的東西，這時他們便需要這份文件：
- 例如是某個 API 是做什麼、每一個參數代表什麼，以及回傳了什麼。
- 不用解釋任何原理，也不用加上任何步驟：會看這份文件的讀者不用這些，加了這些只會讓他們分心。
- 資訊為主，並且提供越詳盡的資料越好。
例子
以電話上的行事曆 APP 為例：
- 新手教學：「帶你看看這個 APP 的介面」
- 操作指南：「如何新增一個行程？」
- 概念解釋：「為什麼我們需要每週視圖？」
- 參考文件：「和其他 APP 串通使用時需要的不同參數的用途」
下次需要寫技術文件時，試試用這個方式來寫吧！
如果你覺得這個內容有用，不妨分享給你的朋友。
這是我的 Facebook、Twitter、Instagram 和 Threads，有興趣的話歡迎 Follow。
如果你認為我的文章有幫助，歡迎 請我喝一杯咖啡。
寫作日期： 2023-07-12