Googleが社内のドキュメンテーションスタイルガイドを公開

次の記事

米信用情報サービスEquifaxのデータ漏洩、被害者は最大1.43億人に

ドキュメンテーションは往々にして、後(あと)からの付け足しだ。オープンソースのプロジェクトではとくにそれが多い。そのため新しい人が後日そのプロジェクトに参加しづらくなったり、ときにはヘタなドキュメンテーションのせいでコードがかえってわかりづらくなることもある。そこでGoogleは、デベロッパーがもっと良いドキュメンテーションを書けるために、同社のdeveloper-documentation style guide(デベロッパードキュメンテーションスタイルガイド)を今週一般公開した

これはGoogleが社内的に使っているスタイルガイドと同じもので、KubernetesやDartなどGoogle内部のプロジェクトもこれに従っている。

内容の一例を挙げると:

  • 業界用語のスペリングの統一
    (例: ○data center, ×datacenter)
  • ハイフンの正しい使い方と良くない使い方
  • 受動態でなく能動態で書くべき理由
  • …その他…

また、とくにデベロッパーにとって重要と思われるのは、APIのコードのコメントの書き方や、コマンドラインのシンタックスの良質なドキュメンテーション、などだ。

AtlassianWordPressSalesforceなどもスタイルガイドを公開しているが、基本的な要素を網羅している点ではGoogleがトップではないだろうか。

編者たちは、このスタイルガイドは生き物であり、今後変わるだろう、と言っている。また、たった一つの絶対に正しいスタイルガイド、というものはない、とも言っている。つまりドキュメントの書き方をめぐってMLA派とシカゴ派の口論が今後続いてもよいし、ぼくが本誌の記事を書くときに使っているAP Stylebookのファンがたくさんいても、構わないのだ。

〔訳注: 上図和訳–

できるかぎり使わないように

  • バズワードや技術的ジャーゴン
  • くだけすぎた書き方
  • “please note”や”at this time”のようなプレースホルダー的語句
  • ごたごたした長過ぎるセンテンス
  • すべてのセンテンスが同じフレーズで始まる(”You can”, “To do”など)
  • 今のポップカルチャーに言及すること
  • 顧客や競合他社/競合製品などをだしにしたジョーク

[原文へ]
(翻訳:iwatani(a.k.a. hiwa))