Google 開發者文件風格指南 developer documentation style guide 學習心得筆記

接續前陣子閱讀的 Google Technical Writing Courses,我發現 Google 的這份「Developer documentation style guide 開發者文件風格指南」更是完整,包含更多討論,從基本文法、標點符號到文件格式的編排,每個主題都切割成許多小章節,搭配豐富的例子,很容易閱讀。

整份文件內容有點多,一路看下去可能有點累人,所以我把他當作休閒讀物來看,有空檔就看個幾篇,不知不覺就念完拉。

讀完雖然不會馬上功力大增,但至少會開啟雷達,讓自己對於文字用法更敏感,也對細節更講究,下次撰寫文件的時候,可以更通順的表達意思。

google dev doc - 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,都是個好的開始,接著可以繼續攻略其他文件與教學拉!

Jerry
Jerry

樂於分享的軟體工程師,曾在新創與大型科技公司實習,獲得黑客松競賽冠軍,擔任資安研討會講者。長期熱衷於資訊安全、雲端服務、網路行銷等領域,希望將科技知識分享給更多人。內容轉載請來信:jlee58tw@gmail.com

發表回應