ドキュメント管理は大変だ

　エンジニアをしていると、自分で1からコードを書くことよりも誰かが書いたコードを読んで、仕様変更に対応したり、バグの修正をしたりすることのほうが圧倒的に多い。
にもかかわらず、大抵のコードは読みにくく、それでいて多くの場合、信頼のできるドキュメントなんてものはない。
あったとしても、主人公が物語の最初に手にする、重要な部分が擦り切れて読めなくなった宝の地図のようなもので、かゆいところにだけ手が届かないようなものばかりだ(まさか狙っているのか？)。

独特のエンジニアリング文化に定評のあるGoogleの Documentation Best Practices が公開されていたので翻訳してみる。

以下、稚拙な意訳

ドキュメンテーションのベストプラクティス

"言いたいことはシンプルかつ明確に言え" - ブライアン・カーニハン

最小限の有益なドキュメンテーション

鮮度がよく、正確なドキュメントの小さなまとまりは、種々様々で不完全なドキュメントの集合よりも優れている。

短く、そして有用なドキュメントを書きましょう。不要なものはそぎ落とし、変化するニーズに合わせて全てのドキュメントを継続的に管理、改善する習慣を身につけましょう。
ドキュメントは盆栽のように、頻繁に剪定することで最も有益になります。

このガイドでは、エンジニアがテストを管理、維持していくのと同じように、ドキュメントも最新の状態に保つことを勧めています。以下の2点を目指してください。

本当に必要なものを明確にしてください。(リリースドキュメント、API docs、テストガイドラインetc...)
誤りを頻繁に小さな規模で訂正してください

コードとともにあれ

コードの変更に合わせて、ドキュメントも変更しましょう。これにより、ドキュメントの鮮度は保たれますし、レビュアーにコード変更の意図も伝わりやすくなります。

死んだドキュメントは消し去れ

死んだドキュメントの存在は悪だ。それは生産性を低下させ、エンジニアを失望させ、チームを悪い方向に引きずり込んでしまう。そのドキュメントは、コード自体のエントロピーを増大させてしまいます。家の中がきれいに整頓されていたのなら、あなたが何も言わずとも、友人も綺麗に使ってくれるでしょう。

大規模な掃除を前に、圧倒されるのは無理もないことです。もし、ドキュメントの状態が最悪ならば、次のように改善を行ってください。

満ち欠ける月のように、少しずつ改善されていきます。
まず先に、間違っていると確信が持てるものを削除してください。まず先に削除です。
チーム全体を巻き込んでください。時間をかけてドキュメントの全てに目を通し、消すものと残すものを決めます。
新しくドキュメントを立ち上げ、既存のものをいくつか移行する場合、基本は消すか移行しないかのどちらかです。忘れ物はいつでも取りに帰れます。
継続してください

完璧を目指すな

ドキュメンテーションは十分に意味のある時間において、可能な限り使えるものである必要あります。ドキュメンテーションのレビューとコードのレビューとは本質的な違いがあります。当然、レビュアーはレビュイーに対して改善を求めることができますし、そうするべきですが、一般的にドキュメント作成の際には"完璧であること、よりも、使えるぐらい十分に良いこと"が優先されます。ドキュメントが完璧になるまで、何度もレビューするよりも、ドキュメントの小さな改善を素早く行えることのほうがずっと価値があります。完璧なドキュメントなど存在しません。チームが必要とする知識を学習するにつれて、徐々に改善されてゆくものです。

優れたコードを書くことはできない。優れたコードにするのだ

優れたコードが優れたコードとして完成するのはコンパイルされた時でもテストカバレッジが100%に達したときでもありません。コンピューターが理解できるものを書くのはたやすいことですが、人間とコンピュータの双方が理解できるものを書くことは非常に難しいことです。良いコードを書くことを心掛けている優れたエンジニアであるあなたの使命は、まず人間のために、そして次にコンピュータのためにコードを書くことです。そういった意味で、ドキュメント作成は重要なスキルです。

ドキュメントには簡潔なコメントから詳細な文章まで、様々なものがあります。

インラインコメント
インラインコメントの主な目的は、そのコードがなぜ書かれたのか、どうしてこのような実装になったのか、など、コード自体に含めることができない情報の提供です
メソッドAPIドキュメント
このドキュメントの対象読者は将来のコードの利用者および変更者です。コードがどのような動作するか(ex. これは受け取った文字列から_を取り除くメソッドです)、そのためには何が必要なのかを記している必要があります。当然、メソッドはドキュメントに記載されている通りに動作することをテストで保証する必要があります。
このドキュメントでは、メソッドが受け取る引数、戻り値、制限、また、返す可能性のある例外について記述します。使用方法に関連しない限り、内部的な動作については記述しません。それはインラインコメントで示されるべきです。メソッドのAPIドキュメントを書く際は、実用的であることを意識することが大切です。
クラス/モジュールAPIドキュメント
このドキュメントでは、簡単な例とともにそのクラス/モジュールが何をするのか、その概要を提供します。
クラス/モジュールにいくつかの使用方法がある場合、最も単純な使用方法から記述することを心がけてください。
README.md
優れたREADME.mdは詳細で適切なユーザーガイドになります。README.mdには最低限、次の内容が必要です。
そもそも、このリポジトリは何のためのリポジトリですか？
開発者がまず最初に確認するべきことは何ですか？
このリポジトリは誰によって管理されていますか？また、どこに問い合わせればより詳細な情報が手に入りますか？
詳しくはREADME.mdのガイドラインで

次回

Googleのドキュメントを実際に読んでみた