Google 技術寫作課程：技術寫作一（下）
如何清楚的表達給目標讀者
嗨，你好。此為我自己的學習紀錄，有任何可以進步的地方歡迎告知。
這是技術寫作一的 後半段，前半段請前往 技術寫作一（上）。
原始英文網頁內容如下：
清單與表格 Lists and tables
圖勝表，表勝文。
選擇正確的清單
技術文件常見的型態有：
項目清單（一個一個點）
編號清單（有數字順序）
嵌入式清單（基本上就是一直逗點）
這段雖然覺得很直覺，不過參考他們如何描述各種條列很有意思。
常常跟人請教的時候，會發現請教的對象不一定知道怎麼描述。
有可能就是，有些東西被認為很trivial，然後就沒有嘗試描述過了。
因此常常會有「啊…就那樣啦。你去Google。」
這段其實直接看例子就好。
把原始句型：
改為：
保持項目同性質 Keep list items parallel
不要同時混入句子和單字。
編號清單使用祈使句 Start numbered list items with imperative verbs
這個提醒滿棒的，有時候會沒注意到。
例如：
使用正確的格式 Punctuate items appropriately
完整句子，開頭大寫結尾放句點。不是的話，不要。
製作有用的表格 Create useful tables
幾個參考：
適當的為行命名，不要讓閱讀者猜。
每格內避免放太多內容，如果超過兩句，嘗試別的呈現方式。
同一行或同一格保持項目同性質（不要混雜）。
有些表格在電腦上顯示很棒，手機閱讀體驗很差。
提供脈絡 Introduce each list and table
清單與表格前，盡量提供一個描述，讓閱讀者快速理解。
段落 Paragraphs
開頭很重要 Write a great opening sentence
文章描述閱讀者會快速掃過第一句，然後跳過第二句。
趕時間的時候的確會大致看每一段的開頭，抓我需要的重點。
尤其是第一句必須開宗明義地讓閱讀者知道，接下來要敘述的內容方向。
一個段落一個重點 Focus each paragraph on a single topic
盡量段落內的每一句，都圍繞開頭句帶出的主題。
如果無關，在修訂的時候移到他處或刪除。
段落長短 Don’t make paragraphs too long or too short
太長的會直接忽略，建議3–5句一個段落。
如果非常多太短的段落，嘗試整併為一段。
蛤？為啥？怎麼做？ Answer what, why, and how
好的段落會提供閱讀者：
1. 我要讓閱讀者知道「什麼」
2. 「為什麼」對閱讀者重要
3. 閱讀者要「如何」使用這個資訊。同時，如何知道你所說為真？
直接看例子：
技術文件的閱讀者 Audience
我覺得這其實是最困難的，除非你一開始寫的就只有特定人會閱讀。
就像演講前講者會跟主辦單位再三確認來聽演講的人員組成，但其實辦講座的人常常也不確定到底組成如何（雖然現在有很多事前的問卷調查）。
因此會有一些演講聽起來好像但簡單或太困難。
這段的開頭很可愛，直接說，你們大家應該數學都不錯，來個公式。
然後放了一段40秒影片，看來是特別為課程做的，我快笑瘋：
定義你的閱讀者 Define your audience
許多技術文件花費透過以下方法在定義閱讀者。
問卷調查
使用者經驗研究
焦點團體訪談
文件測試
一個簡單的做法是，先定義你的閱讀者的角色（工作內容），如
軟體工程師
偏技術、非工程的角色（如TPM）
科學家
醫生
理工學系大學生
理工學系研究生
非技術人員
為什麼先用角色（工作內容）分類？
因為大部分相同角色（工作內容）的背景知識和技能會比較相似，例如：
大部分軟體工程師會知道至少一種程式語言、基本演算法、O(n)是什麼。
你無法期待你的非技術閱讀者明白什麼是 O(n) 。
給醫生看的內容會跟給一般民眾看的內容有很大差異。
另外一個他們提的例子是：
教授跟研究所和大學部會用不同的方式解釋同一個東西。（恩，是嗎。）
還有一個問題，就算是同樣的角色（工作內容），例如軟體工程師，也會有各自熟悉的語言和架構。
這都很合理，但這段最有意思的是提醒：
你的閱讀者會受到時間的影響而有知識落差。
例如大學剛畢業和工作十年對微積分的熟悉度。
所以寫作技術文件的時候，必須跟使用者經驗設計一樣，建構使用者輪廓。
了解會閱讀你的技術文件的人，到底是誰。
決定你的閱讀者需要學什麼 Determine what your audience needs to learn
能完成什麼、有沒有學習順序、看完能學到什麼。
為閱讀者而寫 Fit documentation to your audience
如何有同理，站在閱讀者的角度撰寫文件，非常不容易。
幾個方向做參考：
有沒有使用閱讀者會不懂的縮寫或詞彙？
相對沒經驗的人、新來的人會不會有資訊落差？
知識的詛咒：專家有沒有遺漏一些看似簡單但其實需要說明的關鍵內容？
很多人英文不是母語 Simple words
尤其很多正在看你的技術文件的人。選擇時，請用簡單的英文。
避免特定文化用語或慣用語 Cultural neutrality and idioms
例如你特別喜歡籃球或橋牌舉例，沒有這樣背景知識的人會很難理解。
自己寫的時候可能會呵呵笑，覺得自舉例真是太聰明。（你說是不是。）
其實也是一種知識的詛咒。
這邊提到一個有趣的點：
許多使用者會使用翻譯軟體看你的技術文件。
翻譯軟體不太會翻特定文化用語或慣用語。
文件 Documents
前面看了這麼多，終於來談談文件的結構。
定義文件的範疇 State your document’s scope
描述文件會提到的範疇之外，也可以順道描述「不會」提到的範疇。
這不只對閱讀者有幫助，也能幫撰寫者待在正軌上。
定義你的閱讀者 State your audience
幾個建議：
這個檔案是給什麼樣的人看
閱讀前建議你擁有什麼樣的背景知識
閱讀前建議可以先閱讀什麼
重點先講 Establish your key points up front
可以使用 (TL;DR)快速讓人進入狀況。
歡迎參考 kk在寫 優美地使用 Typescript 撰寫 React 就有使用，不愧是kk。
為閱讀者而寫 Write for your audience
這整個課程都在強調這件事情，滿像這幾年產品開發強調 user centered。
這段和前面一些內容覺得重複了，不過內容大概就是：
你的目標對象是？
需要具備什麼背景知識？
讀完可以幹嘛？
組織文件架構 Organize
基本上就是標題那樣，根據你的目標對象，設定適合的閱讀架構。
把主題分成不同段 Break your topic into sections
這邊提供一個流程來幫助我們撰寫技術文件時，拆分大概念跟細項。
先把內容唸出來並錄音，或隨意地寫約3–5分鐘。結束後問自己：
是否用模糊不清的方式描述概念？
是否列出閱讀者需要完成的步驟？
Describe the permutations of properties that a system can express?
（最後一個我不太確定怎麼翻譯比較好，想個幾天再來修正。）
不過這邊的範例不錯，提供參考。
標點符號 Punctuation
這我真的常常亂用。
逗點 Commas
沒有一定的規則，但是覺得句子要換氣的時候，就放一個吧。
或是需要描述好幾樣東西的時候。（例：aaa, bbb, ccc）
不過這邊提到一個我以前很困惑的地方。
如果描述好幾樣東西的時候，到底在and前面要不要放逗號。
aaa, bbb, and ccc （放逗號）
aaa, bbb and ccc （不放逗號）
這個逗號叫做 Oxford comma 或 Harvard comma。
基本上的建議是，直接做成清單就沒這問題。哈。
然後，如果描述的是不同概念，用句點不要用逗點。
分號 Semicolons
句點區分不同的想法，而分號連結他們，連結的也必須是完整句子。
如果想知道分號用得對不對，把分號前後的句子對換，意思應該一樣要通。
至於嵌入式清單，不可以使用分號，要使用逗點。
最後，分號之後，轉折、連接詞要接逗號，如下：
Em-Dashes
類似破折號，這段的描述真的太有趣。
說明了一堆，然後說，其實這些都可以用逗點解決。
翻譯：為什麼選擇用em-dash而不用comma？ 一種感覺。藝術。體驗。記得 — （還故意用）英文標點符號軟綿又有韌性。
我在網路上找到另外一篇分享，有興趣可以當作額外閱讀。
括號 Parentheses
次要的內容或是題外話，用括號。
至於句點要放在括號內還是括號外？
括號內是完整句子，放句點。
不是完整句子？不用。
輕量標記語言 Markdown
滿多技術文件都會用到Markdown。
不會寫的，課程有提供一些資源。
第一個以前玩過，一步一步跟完，你就能在 Notion 裡面 用 Markdown。
第二個是Github的，感覺設計的很漂亮。
Google 技術寫作課程：技術寫作一（下）完成啦。
歡迎指教、批評、交流。
