カヤックSREの今です。
今年も4月に新卒社員を迎え、4月の後半には技術部研修を行いました。
技術部研修の締めには毎年なにかしらのイベントを行うのが恒例になっており、昨年は社内CTFを開催しました。
今年は、カヤックでは2年ぶりとなる社内ISUCONを開催しました。
アジャイル的ドキュメンテーションのこころ
SREチームの橋本です。
アジャイル開発（ウォーターフォールとの対比の意味で）では「ドキュメントを書かない」、とまで言う人はなかなかいないと思いますが、「コードを読めばOK」といった声は実際の開発者からも聞こえることがあります。
ただ現場でドキュメントにより労力が削減できる場面は間違いなく存在し、またそのときには、軽いメモ程度のドキュメントでも間違いなく役に立つものではないでしょうか。 ややメンタル寄りの内容にはなりますが、ここではそうした観点からドキュメンテーションの「ミニマムスタート」を提案したいと思います。
何のためのドキュメント？
要件定義書、基本設計書、詳細設計書……こうした「ドキュメント」を基盤として開発を行うウォーターフォールモデルの開発と比べれば、アジャイルではドキュメントが必須でない、というのは確かにそうでしょう。 しかし何の役にも立たないのか？ と言えばそれは間違いなくNOです。
最もよくあるケースは、チームに新しいメンバーが入ったときでしょう。 既存のプロダクト（システム）を理解するにあたり、非常によく整理されたコードであればディレクトリ構造そのものがアーキテクチャを表現していたりもしますが、世の中そう上手くはいかないものです。
するとそのメンバーは周りから教えを乞うたり（コミュニケーションコストの発生）、手探りでコードリーディングをするしかありません。 新卒の方が毎年入ってくるとすれば、その現場ではこのコストが毎年発生することとなります。
しかしこれは、考えてみると非常にもったいない事態ではないでしょうか。 設計の概要だけでもドキュメントとして残しておけばこのコストは削減されますし、何よりそれは既存のメンバーの頭の中には既にある知識です。それを書き起こす方が、ゼロからプロダクトの理解を獲得するよりはるかに簡単なのは明らかでしょう。
では、メンバーの入れ替わりがないような環境ではどうでしょうか。 私としては、それでもドキュメントが重要だと言いたいと思います。
なぜなら、人は忘れる生き物だからです。 自分で書いたコードですら、間が空くとなにを考えていたか分からなくなってしまうもの。そのコードを書いた意図や背景といった見えない情報は、最初のうち（あるいは触っているうち）は憶えているものの、やがては忘れてしまいます。
世に「情けは人の為ならず」と言いますが、自分のためにドキュメントを書く、という観点はモチベーションの面からしても大切なのではないかと思います。
自分のためのドキュメンテーション
例えば、いつもシェルの履歴から実行しているコマンド。 手打ちするのは面倒だけど、大した内容でもないからつい履歴頼りのままにしてしまうような、そんなコマンドはないでしょうか。
なにかの拍子にこの履歴が消えてしまうと、これもまた地味ながら手間、つまりコストがかかる事態となります。
ローカルにスクリプトとして残すのも確かに一つの手ではありますが、そうではなく他のメンバーも見られる場所、例えばGitHubのWikiにそのコマンドを書いておけば、それも開発・運用などについての一つのドキュメントとなります。
また例えば新規実装で設計が必要な場合、「図を描く」ということ自体はよくするものと思いますが、これも文脈性が高くならないよう自己完結的に描いておけば、pull requestに貼るのみならずWikiに載せてドキュメントとすることも可能になります。
（自己完結的でない、というのは説明が少なくて「わかっている人にしかわからない」という類のものです。例えばシーケンス図の場合、よほど良い名前がつけられていない限り、API名だけ書いてあっても実際になにをやっているかの理解は難しいかもしれません。）
自分の整理のために書くものを、少し丁寧にしておく。 それだけでも、後に多くの人を救えるようなドキュメンテーションの第一歩が踏み出せるはずです。
劣化を恐れる必要はない、はず
ドキュメントはコードやコミットログ、issueを漁って整理する時間を縮めてくれるもの。 とすればドキュメントは、もちろん最新に保たれ続けているのが望ましくはありますが、時が経ち古くなったとしても依然価値があるということになります。
たとえ1年の間更新されていないドキュメントがあったとしても、その1年前までの歴史を紐解く作業が要らなくなったことには変わりないからです。
とはいえ、コードの不正確な理解による悪影響はプロダクトによりさまざまで、ここは一概には言えないところかもしれません。
こうした劣化への対処として、もちろんタイムスタンプに注意するということもありますが、個人的には「根拠となるコードをリンクしておく」ことを心がけています。読み手が記述を検証できるようにしておくことで、劣化してもなお後の人々が役立てられるドキュメントとなるのではないでしょうか。
もっとも影響範囲をちゃんと確認してモジュールに手を加えた（あるいは削除した）つもりが、いつの間にか他のモジュールに依存されていた、そして思わぬ不具合が……なんて事態はなかなか避けられないものですが。
まとめ
- ドキュメンテーションはコミュニケーションやコードリーディングのコストを削ることで、新たなメンバーはもちろん自分の役にも立つ
- 自分のためのメモ感覚で気楽に書いてまずは公開し、段々と充実させ整理していけば良い
- 劣化を避けるために更新し続けなければと気負う必要はなく、劣化が分かってさえいれば依然プロダクト理解の手がかりになる
ついつい後回しにされがちなドキュメンテーションですが、こうした意識によってより多くの現場でドキュメントが重視され、より多くのエンジニアがその恩恵を受けられることを願っています。
