接續前陣子閱讀的 Google Technical Writing Courses，我發現 Google 的這份「Developer documentation style guide 開發者文件風格指南」更是完整，包含更多討論，從基本文法、標點符號到文件格式的編排，每個主題都切割成許多小章節，搭配豐富的例子，很容易閱讀。
整份文件內容有點多，一路看下去可能有點累人，所以我把他當作休閒讀物來看，有空檔就看個幾篇，不知不覺就念完拉。
讀完雖然不會馬上功力大增，但至少會開啟雷達，讓自己對於文字用法更敏感，也對細節更講究，下次撰寫文件的時候，可以更通順的表達意思。
以下是 Google 開發者文件風格指南的網站位置：
傳送門：Google developer documentation style guide
如果時間不夠的話，直接看文件裡的 Highlights 部分就可以。
另外，從這份文件的改版紀錄來看，他有不斷在更新，之後也許會有更多新內容也說不定。
關於這份風格指南，我整理了一些覺得有用的重點，如果你想要知道更多詳細的說明與指引，建議還是去網站參觀喔。
- Key Resource
- General Principe
- Language and Grammar
- Punctuation
- Formatting and organization
- Computer Interface
- HTML and CSS
- Names and naming
Key Resource
這裡整理了許多用字範例，可以快速喵過去，針對常用的詞彙仔細看就好了。有些詞彙是跟 Android、Google Cloud 有關，沒在用就直接略過。
換成更容易理解的字詞
- abort、kill：有異常終止的意思，可以換成 stop、exit、cancel 或是 end。
- allows you to：換成 lets you。
- enable：開啟某某功能時使用 enable，別用 turn on。如果是讓人可以做某些操作，換成 lets you。
- pros、cons：換成 advantages 與 disadvantages。
- desire、desired、wish：使用 want、need。
- grayed-out：使用 unavailable。
- once：如果指的是 after，那用 after 就好。
- repo：使用 repository。
這樣寫會更好
- and so on：使用 etc. 或者用列舉的方式如 such as、including。
- above、below：換成 preceding 與 following。
- between versus among：among 用在相同的東西上。例如 You can share services among multiple clients。
- contents：使用複數。
- impact：不要當作動詞使用。像是可以改成 This issue affects
(impacts)user experience。 - just：不要用 just 刪除他通常對句子沒有影響。
- may：表達有機會做甚麼，使用 might，表達的是可以做甚麼，使用 can。
- persist：不要當動詞用。可以說：To make the token persist。
- should、via：避免使用。
- vs.：使用 versus。
- wheater、if：通常 wheater 用於都有可能的情況，if 比較用在二選一的狀況下。
避免意思含糊不清
- access (verb)：換成更具體的 see、edit、find、use、view。
- as：如果你的意思是 because 就用 because 就好。
- blacklist / whitelist：可以用更精確的說法 denylist / allowlist、blocklist / allowlist。
- check：在 checkbox 打勾要用 select。我自己是覺得用 check 或 uncheck 看起來很繞口。
- clear：在 checkbox 取消勾選用 clear。也不要用 unselect。
- with：不要用 with 來描述所有權或表示使用。例如：A handset that has
(with)2 GB of RAM、Use the debugging tool to debug。
General Principe
- 不需要表示禮貌，別用 please，也不要用冗字，像是 at this time。
- 在句子之間是當使用過渡的連接詞：though、this way。
- 不要在文件中預先揭露未來可能釋出的功能。
- 確保內容符合無障礙規範。
- 文件是寫給全球所有人看的，不要用只有特定族群使用的特殊用法。也要理解到很多人會直接用 Google 翻譯來閱讀文件，簡單的句子翻譯起來比較不會有問題。
- 盡量使用現在式、主動語態、不要省略關係代名詞、用簡單的詞彙，確保句子讀起來讓人容易理解。
- 使用友善的語氣，避免使用有歧視意味或與性別有關的詞彙。像是 blind eye、mankind。
- 引用外部資源時，使用連結，不要直接複製內容。
Language and Grammar
- 常用的縮寫如 API、HTML 不需要額外解釋。除非是要寫給不懂的人看。
- 使用主動語態。但如果特別要強調動作、或者是想要忽略主詞時，可以斟酌使用被動語態。像是：The file is saved。
- 不要裝可愛使用擬人化 😁
- 關詞的用法：a, an, the。這篇文章寫得很好：When to Use Articles Before Nouns。
- 如果要請使用者針對某些情境做某些操作，把條件句放在前面。像是：To delete the entire document, click Delete。
- 盡量使用「-n’t」縮寫，因為有時候讀者看太快可能會漏掉 not。
- 提供連結時，不要直接貼上網址，盡量給予有意義的說明。
- 表達可能有複數的情況時，不要使用括號，直接選定一個型態單數或複數。像是 key(s)，如果通常只有一把，就用 key。
- 產品不應該有所有格，需要換個方式描述。例如：The capabilities of Search are vast。
- 使用現在式，避免使用 will、would。
- 使用代名詞讓句子不會含糊不清。
- 使用第二人稱「you」而不是「we」。
- 如果不是要開發者做事，而是描述某個 method 會做的行為時，要加上「-s」。例如：tasks.insert: Creates a new task on the specified task list。
Punctuation
- 使用冒號時句子還是要完整，例如：The fields are defined as follows:。
- 平常不使用刪節號，如果是為了讓句子縮短，可以用它來省略像是 UI 上出現的文字。比如：the button in the UI reads “Save …”。
- 單個字母的複數形式：Mind your P’s and Q’s。
Formatting and organization
- 表示時間的格式：day-of-week, month day, year。例如：Wednesday, January 31, 1993。
- 日期與月份使用數字表示時需要注意。比如「04/05/09」這個表示法在不同國家解讀起來不一樣，在英國代表五月 4 日，而在美國代表四月 5 日。如果要用數字表示，使用這個格式：yyyy-mm-dd。
- 引用新的概念或詞彙時，使用斜體。
- 使用列表時，保持每個項目是對等的概念。比如都是物品、都是句子。
- 用特殊的區塊來補充說明注意事項。如：Note、Caution、Warning。
- 數字應該寫成數值或者是文字。文件內的 Numbers 章節說明得很詳細。我自己印象最深的是：在正常情況下，大於 10 的數字要用數值表示。
- 表示連續多個行為時，可以用箭頭符號「>」讓描述更精簡。
- 不要用「&」來當連接詞，應該完整的寫 and。
Computer Interface
- 撰寫 API 文件時，不論是 class、interface、field、method 都要提供說明。詳情請參考：API reference code comments。
- 以 class 為例，介紹的時候不要以 class 名稱開頭，也不要說「this class will/does ….」
- 如果某個 method 棄用了，可以這樣說明：Deprecated. Use xxx instea。告訴使用者可以怎麼做。
HTML and CSS
- 使用正確有意義的 HTML 標籤
- 在 YAML 或 Markdown 檔案中，不要使用 tab 而是採用兩個空白來做縮排。
Names and naming
- 如果要拿人名舉例，在資安相關領域可以用 Alice、Bob 與 Eve。其他領域則要注意會不會有侵權問題。
- 如果要拿 IP 舉例，可以用 RFC 5737 規範裡專們給文件使用的 IP 位置，如192.0.2.1。這個 IP 是沒有在使用的。
- 檔案名稱裡避免包含底線「_」而是用「-」。
總結
經過了一個禮拜，一點一滴的讀完這整份文件，完成了對於自己的挑戰任務，滿開心的。
我自己是覺得前半部的詞彙、文法以及文件格式的指引是有幫助的，而在閱讀過程中，我發現他會引用外部網站來補充說明，也意外獲得一個可以追蹤的好網站：Quick and Dirty Tips。除了針對文法與寫作有許多小技巧，不論生活大小事都有許多建議欸，果不其名哈哈。
而這份指引的後半部提到頁面呈現和 HTML、CSS 的格式規範，這些東西相對比較不會用到，通常公司或機構都已經有人處理好了，遇到這些格是問題，就看一下前人怎麼做，依樣畫葫蘆就對了。
寫作是不斷進步的過程，也是需要累積大量閱讀不斷練習之後，才有辦法把別人的文字轉化為自己的語言。
不論是上次讀的 Technical Writing Courses 還是這份 Developer documentation style guide，都是個好的開始，接著可以繼續攻略其他文件與教學拉！
