組織大型文件

預估時間： 20 分鐘

您如何將大量資訊組織成一份連貫的文件或網站？或者，您如何將現有雜亂的文件或網站重新組織成易於理解且有用的內容？以下策略可以提供幫助：

• 選擇撰寫單一大型文件或一系列文件
• 組織文件
• 加入導覽設計
• 逐步揭露資訊

何時撰寫大型文件

你可以將一組資訊組織成較長的獨立文件，或一系列較短且相互關聯的文件。一系列較短且相互關聯的文件通常會以網站、wiki、或類似的結構化格式發布。

有些讀者對較長的文件反應較為正面，有些則不然。請考慮以下兩位假想讀者的觀點，他們是你撰寫文件的對象：

• 洪先生覺得閱讀長文件很困難且容易迷失方向。他偏好使用網站搜尋功能來尋找問題的答案。
• 羅小姐習慣瀏覽大型文件。她經常使用網頁瀏覽器內建的頁面搜尋功能來尋找當前頁面上的有用資訊。

那麼，你應該將你的資料組織成單一文件，還是網站中的一組文件呢？請考慮以下指導原則：

• 如果是對某個主題全然陌生的讀者，那麼 how-to 指南、入門概述、和概念介紹這些通常比較適合寫成短文件。例如，對主題完全陌生的讀者可能難以記住大量新的術語、概念和事實。請記住，你的讀者可能是為了快速且大致了解主題而閱讀你的文件。
• 進階的教學文件、最佳實踐指南、和命令列參考手冊則適合做成較長的文件，尤其是針對已具備部分工具和主題經驗的讀者。
• 一個出色的教學文件可以透過文字敘述來引導讀者在較長的文件中完成一系列相關任務。然而，即使是大型教學，有時也可以從拆分成較小的部分而受益。
• 許多較長的文件並非設計成一次閱讀完畢。例如，使用者通常會瀏覽參考手冊來尋找某個指令或參數的說明。

本單元的其餘部分將介紹可用於撰寫較長文件（例如教學和一些概念指南）的技巧。

組織文件

本節提供了一些規劃較長文件的技巧，包括建立大綱和撰寫引言。完成文件的初稿後，您可以將大綱和引言進行比對，以確保沒有遺漏原本打算涵蓋的內容。

為文件擬定大綱

從結構化的高層次大綱開始，可以幫助你將主題分組並判斷哪些部分需要更多細節。大綱能幫助你在開始寫作前調整主題的順序。

你可能會覺得將大綱視為文件的敘事脈絡很有用。雖然沒有標準的大綱撰寫方法，但以下指引提供一些實用的建議，或許對你有幫助：

• 在請讀者執行某項任務之前，先向他們說明為什麼要這麼做。例如，以下清單是一個小節的綱要，該小節包含了檢查與改善網頁無障礙支援（accessibility）的教學：
  • 介紹一款瀏覽器外掛程式，用於檢查網頁的無障礙支援；告知讀者將會使用檢查報告的結果來修復多個錯誤。
  • 列出執行外掛程式和檢查網頁無障礙支援的步驟。
• 將大綱中的每個步驟限制為描述一個概念或完成一項特定任務。
• 組織您的大綱，使文件能在讀者最需要的時候引入相關資訊。例如，讀者在剛開始學習基礎知識時，可能不需要（或不想）在文件前言的部分了解專案的發展歷程。如果你認為專案歷史有其參考價值，則不妨在文件末尾提供指向這類資訊的連結。
• 考慮先解釋一個概念，然後示範讀者如何在範例專案或自己的工作中應用它。交替呈現概念性資訊與實務步驟的文件，通常是特別吸引人的學習方式。
• 在開始起草之前，先與您的貢獻者分享大綱。如果您正在與一個未來會審閱和測試您的文件的貢獻者團隊合作，大綱特別有用。

大綱練習

檢視並更新以下長篇教學引言（introduction）的高階大綱。要完成此練習，你可以採取以下任一方式：

• 重新排列現有主題。
• 添加您認為應包含在引言中的任何遺漏主題。
• 刪除您認為與引言無關的任何主題。

## 專案歷史

描述專案的開發歷史。

## 先決條件 (Prerequisites)

列出讀者在開始之前應熟悉的概念，以及任何軟體或硬體要求。

## 系統設計

描述系統如何運作。

## 目標讀者

描述此教學是針對哪些讀者而寫。

## 環境設定

說明如何設定您的環境以便進行本教學的操作。

## 疑難排解

解釋如何診斷和解決在進行本教學的相關步驟時可能發生的問題。

## 相關術語

列出讀者為了理解教學內容所需要了解的術語定義。

## 目標讀者

描述此教學是針對哪些讀者而寫。

## 先決條件 (Prerequisites)

列出讀者在開始之前應熟悉的概念，以及任何軟體或硬體要求。

## 環境設定

說明如何設定您的環境以便進行本教學的操作。

## 相關術語

列出讀者為了理解教學內容所需要了解的術語定義。

介紹一份文件

如果讀者覺得當前的主題不是他要找的，可能就會忽略這份文件。為了讓讀者先了解概況，我們建議在文件開頭提供一段介紹，包含以下資訊：

• 文件涵蓋的內容。
• 預期讀者應具備的先備知識。
• 文件未涵蓋的內容。

請記住，您應該讓文件容易維護，因此不要試圖在介紹中涵蓋所有內容。

以下段落以虛構的文件發佈平台 Froobus 為例，示範如何運用前面列出的要點來撰寫概述（overview）。

本文件說明如何使用 Froobus 系統來發佈 Markdown 檔案。
Froobus 是一套運行於 Linux 伺服器上的發佈系統，能將
Markdown 檔案轉換為 HTML 網頁。本文件適用於熟悉
Markdown 語法的使用者。若需了解 Markdown 語法，請參閱
《Markdown 參考手冊》。您也需要具備在 Linux 終端機中
執行簡單指令的能力。本文件不包含 Froobus 系統的安裝與設
定說明。如需安裝相關資訊，請參閱《快速入門》。

完成初稿後，請將整份文件與您在概述中設定的期望進行比對。您的介紹是否準確說明了接下來會涵蓋的主題？把這個檢查視為文件品質保證（QA）的一種形式，應該會有一些幫助。

引言練習

在此練習中，請檢查並修改以下這段針對虛構程式語言 F@ 所撰寫的最佳實務指南的介紹。請刪除您認為在此情境中不相關的資訊，並補充您認為缺漏的內容。

本指南列出使用 F@ 程式語言的最佳實務做法。
F@ 是一個於 2011 年由開源社群開發的程式語言。本指南
是對 F@ 程式風格指南的補充。除了遵循本指南中的建議外，
也請務必安裝 F@ 的命令列程式碼檢查工具（linter），並
對程式碼執行檢查。F@ 在醫療產業中被廣泛採用。如果您
有建議要補充到本指南的最佳實務清單中，請在 F@ 的文件儲
存庫中提交 issue。

本指南列出使用 F@ 程式語言的最佳實務做法。
在閱讀本指南之前，請先完成專為 F@ 初學者設計的入門教學。
本指南是對 F@ 程式風格指南的補充。除了遵循本指南中的建議
外，也請務必安裝 F@ 的命令列程式碼檢查工具（linter），
並對程式碼執行檢查。如果您有建議可補充至本指南的最佳實務
清單，歡迎在 F@ 的文件儲存庫中提交 issue。

加入導覽設計

提供導覽（navigation）與提示語（signposting）可確保讀者能夠找到他們需要的資訊，並解決手邊的問題。

清楚的導覽包含：

• 介紹與摘要段落
• 主題內容清楚且合乎邏輯的鋪陳
• 有助讀者理解內容的標題與副標題
• 顯示使用者目前所在位置的目錄選單
• 指向相關資源或更深入資訊的連結
• 指引讀者接下來可學習內容的連結

以下章節的建議可協助您規劃文件中的標題架構。

偏好以任務為導向的標題

請選擇能描述讀者當前任務的標題，避免使用不熟悉的術語或工具名稱作為標題。舉例來說，假設您正在撰寫文件來說明建立新網站的流程。為了建立網站，讀者需要初始化 Froobus framework，而為了初始化，讀者必須執行 carambola 命令列工具。 乍看之下，您可能會想使用以下其中一個標題：

• 執行 carambola 命令
• 初始化 Froobus framework

除非您的讀者已非常熟悉這些術語和概念，否則更直觀的標題可能會更合適，例如：「建立網站」。

每個標題下方都要提供內文

大多數讀者會希望每個標題下方至少有簡短的介紹來說明內容脈絡。請避免在二級標題後直接接三級標題，例如：

## 建立網站
### 執行 carambola 指令

在此範例中，簡短的介紹能幫助讀者快速進入狀況：

## 建立網站

要建立網站，請執行 `carambola` 指令。該指令會顯示一連串提示，協助您設定網站。

### 執行 carambola 指令

標題練習

協助讀者在文件中導航，有助他們順利找到所需資訊並成功使用工具。通常，清晰、有組織的目錄或大綱就像一張地圖，能幫助使用者理解工具的功能架構。

在這個練習中，請改善以下大綱。您可以重新排列、加入、刪除主題，或新增次級項目。

關於本教學
進階主題
建立資產導覽樹
定義資源路徑
定義與建置專案
啟動開發環境
定義與建置資源
下一步
定義映像資源
目標讀者
參考資源（See also）
建立映像資源
定義一個映像專案
建立一個映像專案
教學環境設定
選擇教學資產根目錄
關於本指南

## 關於本教學

### 目標讀者

### 關於本指南

### 進階主題

## 教學環境設定

### 選擇教學資產根目錄

### 啟動開發環境

### 建立資產導覽樹

### 定義資源路徑

## 定義與建構資源

### 定義圖像資源

### 建構圖像資源

## 定義與建構專案

### 定義圖像專案

### 建構圖像專案

## 定義與建構資料庫

### 定義資料庫

### 建構資料庫

## 推送、發佈與檢視資料庫

### 推送資料庫

### 發佈資料庫

### 檢視資料庫

## 設定點資料的顯示規則

### 定義、設定並建構向量資料

## 參考資源（See also）

### 範例資料檔案

## 下一步

逐步揭露資訊

對於習慣自行掌握閱讀節奏的讀者來說，學習新概念、想法與技巧通常很有成就感。但如果一次接觸太多新概念與操作指示，也可能令人感到難以招架。當資訊能夠在適當時機逐步揭露，讀者通常會更願意接受篇幅較長的文件。以下幾項技巧可協助你在文件中有效運用「逐步揭露（progressive disclosure）」的原則：

• 盡可能在需要使用某術語或概念的指令附近才介紹它們。
• 拆解大段文字。為了避免單頁中出現多個長段落，應視時加入圖片、表格、清單與標題。
• 拆分冗長的操作步驟。若步驟繁複，試著將其重組為較短的清單，逐步說明如何完成子任務。
• 先從簡單的範例與指令開始，然後逐步加入更有趣、更複雜的技巧。例如，在建立表單的教學中，先說明如何處理文字回應，再介紹如何處理選擇題、圖片或其他回應類型。

下一單元： 製作插圖