文件

預估時間: 10 分鐘

你能寫出句子,也能寫一些段落。那麼,你能否將這些段落整理成一份合乎邏輯的文件?

定義你的文件範圍

好的文件會在一開始就定義其範圍(scope)。例如:

本文件描述「Frambus 專案」的設計。

更進一步的版本會明確指出非範圍——即那些讀者可能會以為應該包含,但實際不在本文件涵蓋範圍內的內容。例如:

本文件不會說明相關技術 Project Froobus 的設計。

範圍說明與非範圍說明不僅對讀者有幫助,對撰寫文件的你也一樣有益。在撰寫過程中,如果文件內容偏離了範圍說明(或進入了非範圍說明的範圍),那你就必須重新聚焦文件內容,或是修改範圍說明。在審閱初稿時,請刪除任何無助於達成範圍說明目標的段落。

練習

請指出以下段落有什麼問題:

本文件說明如何使用 Frambus API 來建立、更新與發布 Fwidgets。本文件不說明如何使用 Frambus API 刪除 Fwidgets,也不涵蓋 Linux 作業系統的歷史。


非範圍部分僅應包含使用者合理期待本文件會涵蓋的資訊。沒有合理的使用者會期待本文件會涉及 Linux 的歷史。

指出目標讀者

好的文件會明確指出其目標讀者。例如:

本文件針對以下族群:

  • 軟體工程師
  • 專案經理

除了讀者的職位,好的讀者聲明還會指出任何先備知識或經驗。例如:

本文件假設你已理解矩陣乘法與反向傳播的基本原理。

在某些情況下,讀者聲明還應指出先前必讀的資源或課程。例如:

在閱讀本文件之前,你必須先閱讀《Froobus 專案:新希望》。

在開頭總結重點

工程師和科學家通常很忙,不一定會讀完一份長達 76 頁的設計文件。假設同事們可能只讀第一段,因此務必在文件開頭就回答讀者最重要的問題。

專業寫作者會將大量精力放在第一頁,以提高讀者願意繼續閱讀的可能性。但第一頁常是最難寫的。因此要準備多次修改第一頁。

比較與對比

在你的職涯中,很少會撰寫含有真正革命性概念的文件;大部分都是漸進式改良,建立在現有技術與概念之上。因此,請將你的想法與讀者已熟悉的概念進行比較與對比。例如:

這個新應用程式與 Frambus 應用程式相似,但圖形效果更佳。

或者:

Froobus API 處理與 Frambus API 相同的使用案例,但 Froobus API 更易使用。

練習

指出以下這段簡介有什麼問題:

Frambus 天氣應用程式 v2 推出十項功能,是 v1 所不具備的。最重要的是,v2 提供兩週天氣預報,而 v1 只有一週預報。潮汐資訊不會改變。


最後一句(關於潮汐的部分)不夠重要,不應出現在開頭。因為第一句提到有十項新功能,讀者自然會期待聽到更多,然而最後一句卻談及不是新功能的內容。

為讀者而寫

本課程反覆強調定義讀者的重要性。本節聚焦於如何運用讀者定義來組織文件。

定義讀者需求

回答下列問題能幫助你確定文件內容:

  • 你的目標讀者是誰?
  • 他們的目標是什麼?為何要閱讀這份文件?
  • 在閱讀之前,他們已經具備什麼知識?
  • 閱讀之後,他們應該知道或能做什麼?

例如,假設你發明一種新的排序演算法,它與快速排序(quicksort)相似。以下是可能的回答:

  • 你的目標讀者是誰?
    目標讀者:本組織的軟體工程師。
  • 他們的目標是什麼?
    讀者的目標:想找到更高效的排序方法,並閱讀本文判斷這種方法是否值得實作。
  • 在閱讀之前,他們已經具備什麼知識?
    讀者的先備知識:會寫程式,曾學習排序演算法,包括快速排序,但多年未實作或評估排序演算法。
  • 閱讀之後,他們應該知道或能做什麼?
    讀者在閱讀後能做這些:
    • 理解此演算法與快速排序的比較與差異。
    • 辨識本演算法在兩種類型資料集上的性能優勢。
    • 以任一編程語言實作此演算法。
    • 辨識兩種執行效率不佳的邊界情況。

根據讀者需求組織文件

在定義完讀者需求後,將文件組織得有助讀者取得所需資訊。例如,根據上述答案,文件大綱可如下:

  1. 演算法概述
    • 與快速排序比較,包括 Big O 複雜度比較
      • 連結至快速排序法的維基百科文章
    • 演算法適用的最佳資料集
  2. 演算法實作
    • 以虛擬碼(pseudocode)實作
    • 實作建議與常見錯誤
  3. 深入分析
    • 邊緣案例(edge cases)
    • 已知的未知(known unknowns)



下一單元: 標點符號 (選修)

Last update: 2025-07-21