文件

預估時間： 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）相似。以下是可能的回答：

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

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

下一單元： 標點符號（選修）

Last update: 2025-07-21