助程式員制作更劃一開發者文件 Google 公開內部編寫指引

寫 Code 厲害的人不代表寫開發者文件也同樣出色,而混亂的開發者文件只會讓接手項目的程式員感到困感。這些問題在不少公司都有發生。Google 日前便公開內部的開發者文件編寫指引,協助開發者制訂更劃一、易懂的文件,方便項目開發。

寫 Code 厲害的人不代表寫開發者文件也同樣出色,而混亂的開發者文件只會讓接手項目的程式員感到困感。這些問題在不少公司都有發生。Google 日前便公開內部的開發者文件編寫指引,協助開發者制訂更劃一、易懂的文件,方便項目開發。

 

一直以來 Google 都有開發者文件編寫指引供內部使用,而現在為了協助外部開發者參與 Google 開源項目的開發,如 Kubernetes、AMP、Dart 等,Google 已將指引公開(Google Developer Documentation Style Guide),期望文件格式可更加一致。

指引內容廣泛,例如文法上,文件建議使用第二身人稱、現在式、主動句等;又或者在字眼選擇方面,縮寫和全寫在何時使用等。當然,程式碼的格式指引亦包括其中。透過文件,我們知道原來 Google 喜歡用兩個空格鍵而非用 Tab 來增加說明文件內的程式碼縮排。

 

Google 表示指引只供參考,不宜從頭到尾地閱讀,只需在有需要時查找相關的內容便可。

Source : Google