說到英文寫作經驗，讓我最頭疼的大概就是研究所論文吧。
記得有次 meeting，在跟老師討論句子要怎麼寫比較順暢，我不知所措地問老師「我參考了很多篇論文，每位作者的風格都不太一樣，也很難抓到要領，應該怎麼寫比較好？」
老師聽完笑了笑，不慌不忙地說道「寫文章齁，就是要多變換句型，這樣人家讀起來才不會呆版、無趣」他建議，除了參考其他論文的寫作方式，也可以試試看最簡單的方式：
換成被動句來形容事情。
但在我看完這篇 Google 的技術文章寫作之後，有種恍然大悟的感覺，原來不能這樣寫技術文件阿！
以前只知道論文的一些寫作眉角，但是進了公司，不論是技術文件，還是內部溝通，寫作方式都略有不同，不可能再用以前這三腳貓的功力打天下。
該唸的書還是要唸，於是我更認命地開始啃食這些教學。以下就是我根據 Google Technical Writing Courses 網站所整理的一些重點，如果你也正在學習的話，可以搭配參考喔。
Google Technical Writing Courses
前陣子 Google 很佛心的公開這個寫作教學資源：
傳送門：Technical Writing Courses
目前有兩堂課，分別是：
- Technical Writing One：the critical basics of technical writing (基本技巧) 約 2 小時
- Technical Writing Two：intermediate topics in technical writing (主題應用) 約 1小時
按照課程建議的進度，大概花三個小時就可以把這些內容看完。我自己邊做筆記邊看，是花差不多時間，如果快速喵過去，估計很快就能掌握要領。
在內容部分，看的出來是專門為工程師而設計，呼應這份教學的標語「Every engineer is also a writer」。裡面的例子都很貼近日常會遇到的狀況，也試著用工程師懂得的比喻來解釋為什麼要這麼寫作。像是有個地方提到工程師喜歡寫精簡程式碼，然後說寫技術文章也應該要這樣 XDD
Software engineers generally try to minimize the number of lines of code in an implementation for the following reasons... In fact, the same rules apply to technical writing
只是解釋個標點符號，怎麼還給我來個變數 N 拉！太理工了喔。
You might be wondering about a list's final comma, the one inserted between items N-1 and N
除了目前這兩堂課之外，Google 還建議你去看開發者社群的寫作指引 Google Developer Documentation Style Guide，那裡面的教學又更多了，好多文件可以挖寶。網路上也有部落客整理分享其他大咖的寫作規範，像是微軟、IBM、Red Hat 等等。真的是太棒啦，接下來這陣子，我有很多教學文件可以專研了！
以下我先列出有用的資源們，有興趣的朋友可以自行前往啃食：
- Microsoft Writing Style Guide
- IBM DeveloperWorks Style Guide
- Red Hat Style Guide
- GitLab Documentation Style Guide
- Google Developer Documentation Style Guide
沒時間的話就看這個重點整理：
Technical Writing One 重點整理
1. Use terms consistently：保持用語的前後一致。有時候可能改前面，忘了後面。
2. Use acronyms properly：必要時使用縮寫。如果該詞彙出現次數很少可以考慮不使用。
3. Disambiguate pronouns：使用代名詞時，要注意前後文是否會造成混淆。
4. Prefer active voice to passive voice：盡量使用主動語態。這個不堪回首，以後要多多注意。
- 大腦在處理訊息時，還是會先把被動語態轉換成主動語態
- 主動語態通常比被動語態短
- 有時候是為了省略主詞才這麼做。改寫時，可以補上合理的主詞
5. Choose strong verbs：選擇適當的動詞，這個還滿重要的，用字精準可以減少不必要的附加說明。避免使用以下者幾個動詞：
- forms of be: is, are, am, was, were, etc.
- occur
- happen
6. Reduce there is/there are：避免使用 there is/there are，有就有，直接寫就好了。如果是為了省略主詞的話，也務必找一個合適的主詞補上去。這個我完全中標阿，整個冗。
❌ There are two disturbing facts about Perl you should know. ⭕ You should know two disturbing facts about Perl.
7. Minimize certain adjectives and adverbs：避免不必要的形容詞與副詞。技術文件與行銷文案不同，盡量使用實際、精確形容詞或副詞。
8. Focus each sentence on a single idea：一句話講一件事就好。我們有時候喜歡把一個句子連得很長，但這樣不好讀，也不容易懂。
9. Convert some long sentences to lists：太多事情的話就用條列式。
10. Eliminate or reduce extraneous words：刪除冗言贅字。像是 is able to 可以改成 can。這條感覺寫完句子後再唸一次就會抓得出來了。
11. Reduce subordinate clauses：跟第八點差不多，如果你的子句說的是另外一個主題，那就拆成兩句話吧。
12. Distinguish that from which：That 與 which 來是有差別的。which 接的是非必要子句。
- Reserve “which” for nonessential subordinate clauses
- Use “that” for an essential subordinate clause that the sentence can’t live without
13. Keep list items parallel：條列中的項目應該是對等的。
14. Start numbered list items with imperative verbs：在數字條列項目中使用祈使句，因為這通常用於指導使用者進行某些操作
15. Introduce each list and table：介紹表格的時候建議還是加上 following。
The following table contains a few key facts about some popular programming languages:
16. Write a great opening sentence：好的開頭要立刻切中核心，讀者不一定有時間慢慢看全文。
Answer what, why, and how：這算是寫文章的基本要領了，好像也沒甚麼好解釋哈。
- What are you trying to tell your reader?
- Why is it important for the reader to know this?
- How should the reader use this knowledge. Alternatively, how should the reader know your point to be true?
17. Fit documentation to your audience：根據你的受眾來調整內容。我覺得大家可能會忽略的是跟程式語言有關的特性或產品本身的特殊用法，需要注意讀者是否都知道。
18. Establish your document’s key points at the start of the document：寫文章前，先把內容範圍、目標族群以及大綱訂好，接著就是填字遊戲了，開始補內容。
19. Punctuation：標點符號倒不是甚麼大問題。如果是條件句，加上逗號會更清楚。
If the program runs slowly, then try the --perf flag.
Technical Writing Two 重點整理
1. Adopt a style guide：遵守公司或機構自己的寫作規範，如果沒有的話，不妨參考看看 Google Developer Documentation Style Guide。
2. Read it out loud、come back to it later：寫完就去休息一下，換個心態再唸一次，通常都會找到可以改進的地方。
3. Find a peer editor：找個人幫你看可能比較難，通常都是遇到問題的時候才會找上你 XD
4. Organizing large documents：寫長文當方式滿直觀的。用 Markdown 來列大綱，然後填充資料還不錯。
- Organizing a document
- Adding navigation
- Disclosing information progressively
5. Write the caption first：製作圖表時，先寫好圖表標題，比較不會迷失方向。
6. Constrain the amount of information in a single drawing：當資訊很多的時候，建議分開描述。可以先用一張架構圖描述大架構，接著再分別用一張圖解釋每個小部份的架構。
7. Creating sample code：概念性的描述盡量寫在文章中，但程式用法的補充說明可以寫在程式碼裡面。畢竟使用者通常是直接複製程式碼去使用，註解也會被一起帶走。
結語
我滿喜歡教學裡的這段話：
Comedy writers seek the funniest results, horror writers strive for the scariest, and technical writers aim for the clearest.
每個角色各司其職，在追求那個領域的最好。對於剛開始修練的人來說，這份文件是一個好的開始，是不錯的入門教材。有許多範例是直接戳到我的痛處，像是「The error occurs when …」我就是用了這種比較通用的動詞，文件上面就建議使用 triggers 或是 generates 比較明確的動詞來描述。
另外，那種被動句，我習慣寫成這樣「The data is generated by …」或是「It is calculated by …」有時候是想說省略主詞沒錯，可確實有可能會讓人覺得迷惑，讀起來也比較繞口。
邊看邊做裡面的練習題，應該會發現不少自己可以改進的地方。閒暇之餘，也可以欣賞這整份文件，這份教學其實就是按照他上面的規範撰寫而成的，也有滿多句子可以學起來用。
接下來我會繼續閱讀 Google Developer Documentation Style Guide，有新的體悟，再跟大家分享！
