ブログで100万の秘訣ってなに?
詳しくはコチラ

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

ドキュメンテーションは往々にして、後(あと)からの付け足しだ。オープンソースのプロジェクトではとくにそれが多い。そのため新しい人が後日そのプロジェクト参加しづらくなったり、ときにはヘタなドキュメンテーションのせいでコードがかえってわかりづらくなることもある。そこでGoogleは、デベロッパーがもっと良いドキュメンテーションを書けるために、同社のdeveloper-documentation style guide(デベロッパードキュメンテーションスタイルガイド)を今週一般公開した。
これはGoogleが社内的に使っているスタイルガイドと同じもので、KubernetesやDartなどGoogle内部のプロジェクトもこれに従っている。
内容の一例を挙げると:
業界用語のスペリングの統一(例: ○data center, ×datacenter)
ハイフンの正しい使い方と良くない使い方
受動態でなく能動態で書くべき理由
…その他…


 
また、とくにデベロッパーにとって重要と思われるのは、APIのコードのコメントの書き方や、コマンドラインのシンタックスの良質なドキュメンテーション、などだ。
AtlassianやWordPress、Salesforceなどもスタイルガイドを公開しているが、基本的な要素を網羅している点ではGoogleがトップではないだろうか。
編者たち

リンク元

コメント

タイトルとURLをコピーしました