文件
預估時間: 10 分鐘
你能寫出句子,也能寫一些段落。那麼,你能否將這些段落整理成一份合乎邏輯的文件?
定義你的文件範圍
好的文件會在一開始就定義其範圍(scope)。例如:
本文件描述「Frambus 專案」的設計。
更進一步的版本會明確指出非範圍——即那些讀者可能會以為應該包含,但實際不在本文件涵蓋範圍內的內容。例如:
本文件不會說明相關技術 Project Froobus 的設計。
範圍說明與非範圍說明不僅對讀者有幫助,對撰寫文件的你也一樣有益。在撰寫過程中,如果文件內容偏離了範圍說明(或進入了非範圍說明的範圍),那你就必須重新聚焦文件內容,或是修改範圍說明。在審閱初稿時,請刪除任何無助於達成範圍說明目標的段落。
練習
請指出以下段落有什麼問題:
本文件說明如何使用 Frambus API 來建立、更新與發布 Fwidgets。本文件不說明如何使用 Frambus API 刪除 Fwidgets,也不涵蓋 Linux 作業系統的歷史。
指出目標讀者
好的文件會明確指出其目標讀者。例如:
本文件針對以下族群:
- 軟體工程師
- 專案經理
除了讀者的職位,好的讀者聲明還會指出任何先備知識或經驗。例如:
本文件假設你已理解矩陣乘法與反向傳播的基本原理。
在某些情況下,讀者聲明還應指出先前必讀的資源或課程。例如:
在閱讀本文件之前,你必須先閱讀《Froobus 專案:新希望》。
在開頭總結重點
工程師和科學家通常很忙,不一定會讀完一份長達 76 頁的設計文件。假設同事們可能只讀第一段,因此務必在文件開頭就回答讀者最重要的問題。
專業寫作者會將大量精力放在第一頁,以提高讀者願意繼續閱讀的可能性。但第一頁常是最難寫的。因此要準備多次修改第一頁。
比較與對比
在你的職涯中,很少會撰寫含有真正革命性概念的文件;大部分都是漸進式改良,建立在現有技術與概念之上。因此,請將你的想法與讀者已熟悉的概念進行比較與對比。例如:
這個新應用程式與 Frambus 應用程式相似,但圖形效果更佳。
或者:
Froobus API 處理與 Frambus API 相同的使用案例,但 Froobus API 更易使用。
練習
指出以下這段簡介有什麼問題:
Frambus 天氣應用程式 v2 推出十項功能,是 v1 所不具備的。最重要的是,v2 提供兩週天氣預報,而 v1 只有一週預報。潮汐資訊不會改變。
為讀者而寫
本課程反覆強調定義讀者的重要性。本節聚焦於如何運用讀者定義來組織文件。
定義讀者需求
回答下列問題能幫助你確定文件內容:
- 你的目標讀者是誰?
- 他們的目標是什麼?為何要閱讀這份文件?
- 在閱讀之前,他們已經具備什麼知識?
- 閱讀之後,他們應該知道或能做什麼?
例如,假設你發明一種新的排序演算法,它與快速排序(quicksort)相似。以下是可能的回答:
- 你的目標讀者是誰?
目標讀者:本組織的軟體工程師。 - 他們的目標是什麼?
讀者的目標:想找到更高效的排序方法,並閱讀本文判斷這種方法是否值得實作。 - 在閱讀之前,他們已經具備什麼知識?
讀者的先備知識:會寫程式,曾學習排序演算法,包括快速排序,但多年未實作或評估排序演算法。 - 閱讀之後,他們應該知道或能做什麼?
讀者在閱讀後能做這些:- 理解此演算法與快速排序的比較與差異。
- 辨識本演算法在兩種類型資料集上的性能優勢。
- 以任一編程語言實作此演算法。
- 辨識兩種執行效率不佳的邊界情況。
根據讀者需求組織文件
在定義完讀者需求後,將文件組織得有助讀者取得所需資訊。例如,根據上述答案,文件大綱可如下:
- 演算法概述
- 與快速排序比較,包括 Big O 複雜度比較
- 連結至快速排序法的維基百科文章
- 演算法適用的最佳資料集
- 與快速排序比較,包括 Big O 複雜度比較
- 演算法實作
- 以虛擬碼(pseudocode)實作
- 實作建議與常見錯誤
- 深入分析
- 邊緣案例(edge cases)
- 已知的未知(known unknowns)
下一單元: 標點符號 (選修)