Google 技術寫作課程：技術寫作一（上）
如何清楚的表達給目標讀者
嗨，你好。此為我自己的學習紀錄，有任何可以進步的地方歡迎告知。
這是技術寫作一的 前半段，後半段請前往 技術寫作一（下）。
原始英文網頁內容如下：
網頁目前分類有：學生(For Students)、討論主持人（For Facilitators）、資源分享（Doc Resources）、招募（The Profession）
先從學生的部分看，有「技術寫作一」和「技術寫作二」，各為2小時和1小時的課前學習時間。課前學習內容設計給軟體工程師、軟體工程學生以及和工程密切合作的職位（如：產品經理）。
技術寫作一總攬 （Technical Writing One introduction）
學習如何把技術文件寫得更清楚。課程的目標族群有特別強調，英文能寫就好，不需要到很厲害。適合沒有寫過技術文件或是需要快速複習的人。
這堂課列的教學目標讓我覺得有點期待，在開始上之前寫一些初始印象：
- Use terminology — including abbreviations and acronyms — consistently. （有時候中英混雜也不是故意，因為溝通上要確保講的是一樣的東西，不知道這邊會討論什麼。）
- Recognize and disambiguate pesky pronouns.
- Distinguish active voice from passive voice.
- Convert passive voice sentences to active voice. （這個很有趣，之前玩Hemingway App，發現我寫作經常用passive voice。）
- Identify three ways in which an active voice is superior to passive voice.
- Develop at least three strategies to make sentences clearer and more engaging. （這個好期待！）
- Develop at least four strategies to shorten sentences. （以前寫作很容易逗點太多，句子太長。）
- Understand the difference between bulleted lists and numbered lists. （啊？好奇）
- Create helpful lists.
- Create effective lead sentences for paragraphs.
- Focus each paragraph on a single topic. （這很重要，讓人掃第一句就知道這段的大概內容。）
- State key points at the start of each document. （畢竟技術文件是要快速找到需要的資源？）
- Identify your target audience.
- Determine what your target audience already knows and what your target audience needs to learn. （其實這是最為困難的，尤其是公開發表的文章，如果是特定族群可能比較好修正？）
- Understand the curse of knowledge. （這真的很有趣，很難讓自己回到不知道的狀態。）
- Identify and revise idioms.
- State your document’s scope (goals) and audience.
- Break long topics into appropriate sections.
- Use commas, parentheses, colons, em-dashes, and semicolons properly. （好，以前有時候都亂用。）
- Develop beginner competency in Markdown. （好懷念，當初寫的docs都是用Markdown。）
夠用的文法（Just enough grammar）
對於英文非母語，必須經過漫長痛苦文法學習的人們，可能會比較直覺？
這單元非必要（Optional）
名詞 Noun、代名詞 Pronoun、形容詞 Adjective、動詞 Verb、副詞 Adverb、介系詞 Preposition、連接詞 Conjunction、轉折詞 Transition。
全部都例子還有小測試，測試句子都很有趣，例如「請找出所有動詞」。
文字 Words
這部分的討論滿實際的，如：
定義新的或不熟悉的詞彙
- 如果詞彙已存在，附上適當的鏈結（不要重複造輪子）
- 如果是新的，在這份文件上定義，或提供詞彙表
用詞一致
- 不知道是不是因為設定給軟體工程背景的人看，這邊的舉例是：亂改變署名就不能編譯，所以寫文件的時候用詞不一致，閱讀的人腦袋也無法編譯喔。滿可愛的，但這樣的舉例效果比較好嗎？
- 反正，最前面怎麼寫，後面怎麼寫。當然也可以定義完之後，提供縮寫，之後都用縮寫。
使用縮寫
- 第一次使用的時候，用粗體，把全名寫出來，縮寫用括號。如：American Born Chinese (ABC)，之後就可以一直叫人家ABC了
- 文內不要前面縮寫、後面全寫
- 如果會出現很平凡，才考慮用縮寫
- 如果縮寫確實短很多，才考慮用縮寫
明確的使用代名詞
- 使用代名詞要描述的名詞後，才能使用代名詞
- 代名詞要離名詞越進越好，一個參考基準是距離不超過五個字，超過就直接用名詞
- 如果名詞跟代名詞中間會出現另外一個名詞，不要使用代名詞
- 「明確的使用代名詞」這段很有趣，能確保正確的描述（例如我原本只打算寫這段…）
主動語態 vs. 被動語態 Active voice vs. passive voice
裡面附了一個影片（40秒），我覺得滿清楚。
舉了不少例子，說明應該以主動語態為主撰寫文件，偶而用被動語態。
- 大部分的閱讀者讀到被動語態，腦中還是用主動語態的邏輯在思考，應該避免這樣的轉換成本。
- 被動語態會造成理解困難
- 主動語態句子通常比較短
最後有補充一個科學研究常常出現被動語態的部分，我覺得例子很可愛，是1953年Nature文章的一段。（灰色部分）
教材寫「作者們對他們的發現興奮到在屋頂上耳語」(“The authors are so excited about their discovery that they’re whispering it from the rooftops.”)
這種半開玩笑的方式（例子描述興奮就該大聲的喊出來，為了指出這邊用主動語態會更好）滿戳中我的笑點的。
清晰的句子 Clear sentences
這段提到技術寫作很重視清楚的表達，而動詞的選擇會影響最大。
建議少用 be 動詞
（如：is, are, am, was, were, etc.）和 occur 或 happen。
Occur 相對被動，這邊例子使用 trigger 代替。
減少 There is / There are
這很常見，某些句子開頭直接拿掉 There is/ There are 不影響句子也更精煉。
或可能是這種情形：
或沒有主詞的時候，直接提供有意義的主詞。
減少特定形容詞或副詞
最後提醒我們，技術文件不是行銷文件，是教育用不是銷售用。
與其說「效能飛快」不如寫「效能提升百分之二十」。
短句 Short Sentences
寫得精簡，容易維護、減少錯誤、容易閱讀。
一個句子一個概念
讀起來就不用來回看，一次搞懂一件事情，就往下。
長句不如列表
尤其有步驟或是細項很多，可考慮條列。
減少多餘贅字
這裡列了一些常見的，把左邊的改為右邊，意思不變。
會不會其實反而英文不熟悉的人來寫英文技術文件，贅字會比較少？
考慮減少從句
這裡呼應「一個句子一個概念」，底下列出部分常見從句開頭，可考慮獨立成一個句子。
- which
- that
- because
- whose
- until
- unless
- since
分辨 that 和 which
我開始覺得這不是美國人寫的。可能是美國長大的某裔美國人。
“…, alert American readers will angrily announce that you confused the two words again.” （翻譯：美國讀者會憤怒的跟你說你搞混兩個字了。）
笑翻。
不過這邊的分辨方法很有意思，用唸出來的方式看是否有停頓。
最後， which 前面要加逗號、that 前面不用。
