清單與表格

預計時間：15 分鐘

好的清單可以將技術上的混亂轉化為井然有序的內容。技術讀者通常喜歡清單。因此，在撰寫時，請尋找機會將段落文字轉換為清單。

選擇正確的清單類型

以下類型的清單在技術寫作中佔主導地位：

• 項目符號清單
• 編號清單
• 嵌入式清單

對於無序的項目，請使用項目符號清單；對於有序的項目，請使用編號清單。換句話說：

• 如果您重新排列項目符號清單中的項目，清單的含義不會改變。
• 如果您重新排列編號清單中的項目，清單的含義會改變。

例如，我們將以下內容設為項目符號清單，因為重新排列其項目不會改變清單的含義：

Bash 提供以下字串操作機制：

• 從字串開頭刪除子字串
• 將整個檔案讀入一個字串變數

相比之下，以下清單必須是編號清單，因為重新排列其項目會改變清單的含義：

請按照以下步驟重新設定伺服器：

1. 停止伺服器。
2. 編輯設定檔。
3. 重新啟動伺服器。

嵌入式清單（有時稱為行內清單）將項目塞入一個句子中。例如，以下句子包含一個有四個項目的嵌入式清單。

llamacatcher API 讓呼叫者可以建立和查詢駱馬、分析羊駝、刪除小羊駝以及追蹤單峰駱駝。

一般來說，嵌入式清單是呈現技術資訊的較差方式。請嘗試將嵌入式清單轉換為項目符號清單或編號清單。例如，您應該將包含嵌入式清單的句子轉換為以下段落：

llamacatcher API 讓呼叫者可以執行以下操作：

• 建立和查詢駱馬。
• 分析羊駝。
• 刪除小羊駝。
• 追蹤單峰駱駝。

保持清單項目平行

是什麼區分了有效的清單和有缺陷的清單？有效的清單是平行的；有缺陷的清單往往不平行。平行清單中的所有項目看起來都「屬於」一起。也就是說，平行清單中的所有項目在以下參數上都匹配：

• 文法
• 邏輯類別
• 大小寫
• 標點符號

相反地，不平行清單中至少有一個項目在上述至少一項一致性檢查中失敗。

例如，以下清單是平行的，因為所有項目都是複數名詞（文法）、可食用的（邏輯類別）、標題大小寫（大小寫），並且沒有句點或逗號（標點符號）。

• 胡蘿蔔
• 馬鈴薯
• 高麗菜

相比之下，以下清單在所有參數上都極度不平行：

• 胡蘿蔔
• 馬鈴薯
• 夏日的光芒掩蓋了所有冬天的回憶。

以下清單是平行的，因為所有項目都是完整的句子，具有完整的句子大小寫和標點符號：

• 胡蘿蔔富含維生素 A。
• 馬鈴薯味道鮮美。
• 高麗菜提供大量的維生素 K。

清單中的第一個項目建立了一種模式，讀者期望在後續項目中看到這種模式的重複。

編號清單項目以祈使動詞開頭

考慮讓編號清單中的所有項目都以祈使動詞開頭。祈使動詞是一個命令，例如 open 或 start。例如，請注意以下平行編號清單中的所有項目都以祈使動詞開頭：

1. 從 Google Play 或 iTunes 下載 Frambus 應用程式。
2. 設定 Frambus 應用程式的設定。
3. 啟動 Frambus 應用程式。

以下編號清單不平行，因為其中兩個句子以祈使動詞開頭，但第三個項目沒有：

1. 實例化 Froobus 類別。
2. 呼叫 Froobus.Salmonella() 方法。
3. 過程停滯。

適當地為項目加上標點符號

雖然不同的風格指南對清單項目的標點符號提供了相互矛盾的建議，但 Google 開發者文件風格指南建議（有一些例外）每個清單項目都以大寫字母開頭。例如：

• 迴圈
• 條件式
• 變數宣告

如果清單項目是一個句子，請使用適當的句尾標點符號。例如：

• 開啟程式。
• 點擊設定圖示。

建立有用的表格

善於分析的人往往喜歡表格。如果一個頁面包含多個段落和一個表格，工程師的目光會迅速轉向表格。

建立表格時請考慮以下準則：

• 為每一欄加上有意義的標頭。不要讓讀者猜測每一欄的內容。
• 避免在表格儲存格中放入過多文字。如果一個表格儲存格包含超過兩個句子，請自問該資訊是否屬於其他格式。
• 雖然不同欄可以包含不同類型的資料，但應力求在單一欄內保持平行。例如，特定表格欄中的儲存格不應混合數字資料和著名的馬戲團表演者。

注意： 有些表格在所有裝置上都無法良好呈現。例如，在筆記型電腦上看起來很棒的表格，在手機上可能會看起來很糟糕。

為每個清單和表格加上引言

我們建議為每個清單和表格加上一個引言句，告訴讀者該清單或表格代表什麼。換句話說，為清單或表格提供上下文。引言句以冒號而不是句點結尾。

雖然不是強制要求，但我們建議在引言句中加入「以下」一詞。例如，考慮以下引言句：

以下清單標識了關鍵效能參數：

請按照以下步驟安裝 Frambus 套件：

下表總結了我們產品與主要競爭對手產品的功能：

練習

為下表寫一個引言句：

答案範例：

• 下表包含一些關於流行程式語言的關鍵事實：
• 下表標識了三種流行程式語言的發明者、發明年份和主要特點：