ドキュメンテーションは往々にして、後（あと）からの付け足しだ。オープンソースのプロジェクトではとくにそれが多い。そのため新しい人が後日そのプロジェクト参加しづらくなったり、ときにはヘタなドキュメンテーションのせいでコードがかえってわかりづらくなることもある。そこでGoogleは、デベロッパーがもっと良いドキュメンテーションを書けるために、同社のdeveloper-documentation style guide（デベロッパードキュメンテーションスタイルガイド）を今週一般公開した。
これはGoogleが社内的に使っているスタイルガイドと同じもので、KubernetesやDartなどGoogle内部のプロジェクトもこれに従っている。
内容の一例を挙げると:
- 業界用語のスペリングの統一
（例: ○data center, ×datacenter） - ハイフンの正しい使い方と良くない使い方
- 受動態でなく能動態で書くべき理由
- …その他…
また、とくにデベロッパーにとって重要と思われるのは、APIのコードのコメントの書き方や、コマンドラインのシンタックスの良質なドキュメンテーション、などだ。
AtlassianやWordPress、Salesforceなどもスタイルガイドを公開しているが、基本的な要素を網羅している点ではGoogleがトップではないだろうか。
編者たちは、このスタイルガイドは生き物であり、今後変わるだろう、と言っている。また、たった一つの絶対に正しいスタイルガイド、というものはない、とも言っている。つまりドキュメントの書き方をめぐってMLA派とシカゴ派の口論が今後続いてもよいし、ぼくが本誌の記事を書くときに使っているAP Stylebookのファンがたくさんいても、構わないのだ。
〔訳注: 上図和訳–
できるかぎり使わないように
- バズワードや技術的ジャーゴン
- くだけすぎた書き方
- “please note”や”at this time”のようなプレースホルダー的語句
- ごたごたした長過ぎるセンテンス
- すべてのセンテンスが同じフレーズで始まる（”You can”, “To do”など）
- 今のポップカルチャーに言及すること
- 顧客や競合他社/競合製品などをだしにしたジョーク
〕
