受眾

預計時間： 10 分鐘

課程設計者認為你可能對數學感到熟悉。因此，本單元以一個方程式開始：

good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills

換句話說，確保你的文件提供讀者所需但尚未擁有的資訊。因此，本單元說明如何做到以下幾點：

• 定義你的讀者。
• 判斷你的讀者需要學習什麼。
• 讓文件內容符合你的讀者需求。

正如以下影片所示，鎖定錯誤的讀者會造成混亂：

定義你的受眾

認真撰寫文件的工作會花費大量時間和精力來定義其讀者群。這些工作可能包括調查、使用者體驗研究、焦點團體以及文件測試。你可能沒有那麼多時間，因此本單元採用較簡單的方法。

首先從識別你的讀者群角色開始。範例角色包括：

• 軟體工程師
• 技術性非工程師職位（例如技術專案經理）
• 科學家
• 科學領域專業人士（例如醫師）
• 大學工程系學生
• 研究所工程系學生
• 非技術職位

我們很高興看到許多非技術職位的人擁有優秀的技術和數學能力。然而，職位仍然是定義你的受眾時一個重要的初步近似。相同職位的人通常具備某些基本技能和知識。例如：

• 大多數軟體工程師都知道常見的排序演算法、Big O 符號，以及至少一種程式語言。因此，你可以依賴軟體工程師知道 O(n) 的意義，但不能指望非技術職位的人了解 O(n)。
• 針對醫師的研究報告應該與針對一般大眾的同一研究新聞報導有明顯不同的呈現方式。
• 教授向研究所學生解釋一種新的機器學習方法，應該與向大一新生解釋的方式有所不同。

如果同一角色中的每個人都擁有完全相同的知識，寫作會容易許多。不幸的是，同一角色內的知識很快就會分歧。Amal 是 Python 專家，Sharon 擅長 C++，Micah 則精通 Java。Kara 熱愛 Linux，但 David 只懂 iOS。

僅靠角色本身不足以定義受眾。也就是說，你必須考慮受眾與知識的接近程度。Project Frombus 的軟體工程師對相關的 Project Dingus 有所了解，但對無關的 Project Carambola 一無所知。一般心臟專科醫師比一般軟體工程師更了解耳朵問題，但遠不及聽力學家。

時間也會影響親近度。例如，幾乎所有軟體工程師都學過微積分。然而，大多數軟體工程師在工作中並不使用微積分，因此他們對微積分的知識會逐漸淡忘。相反地，有經驗的工程師通常比同一專案中的新工程師對目前專案了解得多得多。

範例受眾分析

以下是虛構專案 Zylmon 的範例受眾分析：

專案 Zylmon 的目標受眾包含以下角色：

• 軟體工程師
• 技術產品經理

目標受眾與知識的接近程度如下：

• 我的目標受眾已經熟悉 Zyljeune API，這些 API 與 Zylmon API 有些相似。
• 我的目標讀者懂得 C++，但通常沒有在新的 Winged Victory 開發環境中建置過 C++ 程式。
• 我的目標讀者在大學時修過線性代數，但團隊中許多人需要複習矩陣乘法。

判斷你的讀者需要學習什麼

寫下你的目標讀者為了達成目標需要學習的所有事項清單。在某些情況下，清單中應包含目標讀者需要執行的任務。例如：

閱讀完文件後，讀者將會知道如何執行以下任務：

• 使用 Zylmon API 依價格列出飯店。
• 使用 Zylmon API 依地點列出飯店。
• 使用 Zylmon API 依用戶評分列出飯店。

請注意，您的讀者有時必須按照特定順序掌握任務。例如，您的讀者可能需要先學會如何在新的開發環境中建立和執行程式，然後才學習如何撰寫特定類型的程式。

如果您正在撰寫設計規格，則您的清單應該著重於目標讀者應該學習的資訊，而非掌握特定任務。例如：

閱讀設計規格後，讀者將學習以下內容：

• Zylmon 優於 Zyljeune 的三個原因。
• Zylmon 花費 5.25 個工程年開發的五大原因。

讓文件符合你的讀者需求

為了滿足讀者的需求而撰寫，需要無私的同理心。你必須創造出能滿足讀者好奇心的說明，而非僅僅是自己的好奇心。你該如何跳脫自我，讓文件符合讀者的需求？很遺憾，我們無法提供簡單的答案，但我們可以提供幾個可聚焦的參數。

詞彙與概念

將你的用詞與你的受眾相匹配。

注意距離感。你團隊中的人可能了解你們團隊的縮寫，但其他團隊的人是否也能理解這些縮寫呢？隨著目標受眾的擴大，請假設你必須解釋更多內容。

同樣地，你軟體團隊中有經驗的人可能了解團隊專案的實作細節和資料結構，但幾乎所有其他人（包括團隊中新加入的成員）都不了解。除非你是專門為其他有經驗的團隊成員撰寫，否則通常你必須解釋比預期更多的內容。

知識的詛咒

專家經常會遭遇知識詛咒，意指他們對某個主題的專業理解反而破壞了對新手的解釋。作為專家，很容易忘記新手並不知道你已經知道的事情。新手可能無法理解那些只稍微提及微妙互動和深層系統，且專家不會停下來解釋的說明。

從新手的角度來看，知識詛咒就像是因為模組尚未編譯而出現的「找不到檔案」連結器錯誤。

練習

假設以下段落是針對從未編程過的醫師所撰寫論文的開頭。請指出該段落中存在哪些知識詛咒的部分：

C 是一種中階語言，層級高於組合語言，但低於 Python 和 Java。C 語言讓程式設計師能夠對程式的各個方面進行細緻的控制。例如，使用 C 標準函式庫，可以輕鬆地配置和釋放記憶體區塊。在 C 語言中，直接操作指標是很平常的事。

假設前述段落的目標讀者是剛接觸 C 語言但已熟悉 Python 的大學電腦科學新生。這段文字是否仍然受到知識詛咒的影響？

答案：

這段文字嚴重受到知識詛咒的影響。目標讀者從未寫過程式，因此以下術語對他們來說不適當或不熟悉：

• 語言
• 中階語言
• 組合語言
• Python
• Java
• 程式
• C 標準函式庫
• 配置與釋放記憶體區塊
• 指標

這段文字對於另一類讀者來說也遭遇了知識詛咒。一般的 Python 程式設計師並不熟悉記憶體操作或指標。更好的入門段落應該比較並對照 C 與 Python。

簡單用詞

英語已成為全球技術溝通的主要語言。然而，有相當比例的技術讀者在非英語語言中更感舒適。因此，應偏好使用簡單詞彙，避免使用過時或過於複雜的英語詞彙。冗長且罕見的詞彙會讓部分讀者感到排斥。

文化中立性與成語

保持你的寫作文化中立。不要要求讀者必須了解 NASCAR、板球或相撲的複雜細節，才能理解一個軟體的運作方式。例如，以下這句充滿美式棒球隱喻的句子，對某些巴黎讀者來說可能會感到困惑：

如果 Frambus 5.0 是一支安打，Frambus 6.0 就是一支站立二壘安打。

成語是指整體意義與該短語中各個字詞的字面意義不同的片語。例如，以下這些片語就是成語：

• 輕而易舉
• 事情就這麼簡單

蛋糕？Bob？大多數來自美國的讀者會認出第一個成語；大多數英國讀者會認出第二個成語。如果你是專門為英國觀眾寫作，那麼「事情就這麼簡單」是可以接受的。然而，如果你是為國際觀眾寫作，建議用「這項任務完成了」來替代該成語。

成語深植於我們的語言中，以至於成語的特殊非字面意義對我們來說變得無形。換句話說，成語是知識詛咒的另一種形式。

請注意，您的部分讀者會使用翻譯軟體來閱讀您的文件。翻譯軟體通常較難處理文化參照和成語，比起簡單明瞭的英文更容易出錯。

練習

找出以下句子的問題：

• 截至版本 3.0，呼叫 Frambus 方法仍然是可接受的。
• 決定哪些 BlogResource 限制可以組合是一個棘手的問題。
• 儘管如此，你仍然必須撰寫單元測試。

答案：

• 在世界某些地方，kosher 已成為「可接受使用」的俚語。然而，許多讀者會好奇宗教飲食法規如何與軟體相關。
• A sticky wicket 是英國俚語，不易被其他地區理解。用「棘手的問題」來替代這個詞組可以解決這個問題。
• 「Be that as it may」是一個成語。用轉折詞「然而」來替代可以解決這個問題。