文件

保持文件組織化，使用「集合（collections）」功能，根據喜好儲存和分類內容。

預估時間： 10 分鐘

你可以撰寫句子，也可以撰寫段落。你能否將這些段落整理成一份合乎邏輯的文件？

定義你的文件範圍（Scope）

好的文件會在一開始就定義其範圍。例如：

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

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

本文件不說明與其相關的技術「Froobus 專案」的設計內容。

範圍與非範圍聲明不僅對讀者有益，對作者你也很重要。當寫作內容偏離範圍聲明（或闖入非範圍聲明）時，需要重新聚焦或修改你的範圍聲明。在審閱初稿時，刪除任何無法協助達成範圍聲明目標的章節。

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

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

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

好的文件會明確指出其讀者對象。例如：

本文件針對以下族群：
軟體工程師
專案經理（PM）

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

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

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

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

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

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

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

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

或：

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

指出以下介紹段落有什麼問題：

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

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

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

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

例如，假設你發明一種新的排序演算法，它與快速排序（quicksort）相似。以下是可能的回答：

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

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

內容授權

除非另有說明，該頁面內容採用 Creative Commons Attribution 4.0 授權，程式碼範例則採用 Apache 2.0 授權。Java 為 Oracle 及其關聯公司之註冊商標。

最後更新日期：2025‑03‑28 UTC

如果你想繼續翻譯更多章節，或需要進一步說明，隨時告訴我！

Last modified: 2025-07-04