オライリーのGoogleのソフトウェアエンジニアリング - ドキュメンテーション

この記事の概要

昨年末にオライリージャパンから出版された
Googleのソフトウェアエンジニアリングのドキュメンテーションに関する章の内容を備忘のため個人的にまとめた内容です。
本の内容に追加して私の主観や感想が入りまくった記事になるため、時間がある方は本を直接お読みになられることをオススメします。
チームビルディングやテストに関する内容など、非常に参考になる内容が多いため読んでみてください（まだ全部読んでないけど）。

チームのドキュメンテーションに関する前提と課題感

• ドキュメントを作成する開発者は作成したことの恩恵を受けることは稀で、基本的には読者がその恩恵を得る

• 作成したことによって効果が出るのは、新メンバー加入時やある程度時間が経った後に確認する際など、長期的である

• ドキュメントはそのコードを書いたエンジニアが作成することになる。それを効果的に書くためには適正なツールとインセンティブが必要（面倒くさいため）

• ドキュメンテーションは短期的には面倒な作業であるが、長期的な観点で考えると作成コストに対して十分な効果がある

• 定着を目指すためには既存のワークフローにプロセスを導入する必要がある

• 開発チームが他者が書いたコードの修正を行う際など、質の高いドキュメントがないことが課題感としてあげられる

  • 例えば・・・
    • このドキュメントって最新？
    • 特定の手順でエラーがでるけど、どうすりゃいいの？
    • このメソッドやクラスを使うときの影響や注意点は？

一言でまとめると、「短期的な効果が見えにくいため面倒な作業であることは理解したうえで、仕組み化することや動機付けが必要である」 と大変共感できる課題感でした。

これらの課題に対してどうするべきか？

• コードと同様にドキュメントにもオーナーがいるべき
  • オーナーが明確でない場合、保守が定常的に行われない
• Googleではコードレビューと同様にドキュメントレビューも行われている
  • 3ヵ月間確認が行われていないドキュメントのオーナーには、メールでリマインドが行われるほどの仕組み化が行われている
• コードファイルの冒頭には、1-2段落でそのコードがなにをするかの概要となる説明が必要
  • クラスや関数の説明としては、
    • ＸＸをした文字列を返す。intが引数として与えられた場合は、変換したうえで文字列を返す。それ以外の場合は、ＺＺＺの例外を発生させる
    • 👆のように、一つの段落で処理を網羅的に書くと良い

一言でまとめると、「ルール化と仕組み化が大事」

ドキュメンテーションのTips

• プログラムに関するドキュメントは従来的には「How？」を意識しており、その他の誰に向けたものか？、何がこのドキュメントの目的か？ などが記載されていないことが多い。
• 技術的なドキュメントにおいても、読み手の分かりやすさをあげるためには上記のようなHow以外の概要や目的の記載が必要

ドキュメントに記載するべき内容（例）

- 目的
    - このドキュメントは、〇〇の開発環境であるPython3.9の仮想環境を作成し、githubにCommitができるまでの手順を記載している。
- 想定読者
    - 〇〇プロダクトに新しくジョインした新メンバーが環境構築を行うために読むことを想定
- 必要な情報の場所
    - Git repoのリンクなど
- 最終更新者
    - パブロ（更新者名）
- 最終更新日
    - 2022/04/01

まとめ

ドキュメント作成を面倒に感じてしまうのは当然のことだと再認識しました。短期的には作成コストに目がいってしまい、億劫になるのも当然であるなと。

しかし、チームのメンバーが増えていくことやメンバーの入れ替わりが発生した際など長期的な観点で見ると必要不可欠であり、コストに対して十分な効果があるということも改めて感じました。

主観的な考えですが、チームにおいて即効性が高い施策としては、

• ドキュメントレビューをコードレビューのタイミングで同様に行うこと
• ドキュメントに対するオーナーを明確にすること
  • メンテナンスを定常的に行うための仕組み化も含めて（Googleの場合はリマインドメール)
• 誰に向けて書いたドキュメントであるか/目的とする範囲を明記すること
  • 開発未経験新メンバーと習熟度の高いメンバーでは、理解に必要な情報量が違う

このあたりを意識するとチームとしての長期的な強さを高められるのではなかろうかとの所存です。この記事を読んで気になった方は、本をお読みください。