サービス開発チームでのドキュメント管理

Cloud Automatorを開発しているサービス開発課では開発のプラットフォームにGitHubを用いており、ドキュメントの作成・管理はGitHubのWikiを活用しています。

Wikiには主として、

各機能の仕様や開発の経緯まとめ
技術検証内容のまとめ
何らかの手順
構成内容

等を記載しています。

サービス開発課でのGitHub Wikiの活用は2014年頃から始めていたそうで、2021年末時点で400以上のWikiページが存在していました。

それらの中にはドキュメントの内容が明らかに古くなっていたものや、他のページと位置づけが重複したもの等が存在していました。

それらは削除しても良さそう、ないし削除した方が良さそうではあったものの、チーム内の他のメンバーが参照していたり、削除すべきでない情報が残っている可能性があったため、気軽に削除することは出来ませんでした。また、数もそれなりに多かったため、都度都度確認していくのも大変でした。

年末の大掃除

そこで、昨年末、ドキュメントの大掃除として、削除可能そうなドキュメントを1つずつチーム内でレビューしていき、2014年から2019年までのドキュメントすべて要不要を確認していくこととしました。その結果、約100近くのWikiページを削除できました。

削除の判断基準としては主として以下としました。

技術的なメモで内容が既に古くなっており、今後使うことは無いと考えられるもの
手順書で内容が既に古くなっており、今後使うことは無いと考えられるもの

他方、一見内容が古くなっていたとしても、過去の開発の背景や意思決定の理由（例えば開発項目として採用されなかった理由）、以前の機能の仕様等が残されているものは、次の開発の内容を検討する際の参考にできそうなため、削除の対象外としました。

実施してみたところ、思った以上に不要なページがあって驚いた反面、古いと思われたページでもよくみると当時の意思決定の経緯があり、残しておいた方がいいドキュメントがあることもあり、やはりチーム内で見ていくと異なる視点でドキュメントが参照されることがあると分かり、やってよかったと思います。

『Googleのソフトウェアエンジニアリング』

さて、そんな活動をしている中、『Googleのソフトウェアエンジニアリング』をたまたま読んでいたところ、ちょうどドキュメント管理における面白い内容がありました。

古いコードが問題を起こす可能性があるのと全く同様に、古いドキュメントも問題を起こす可能性がある。（略）Googleでは、しばしばドキュメンテーションに「鮮度日時（freshness date）」を付加する。そうしたドキュメントにはドキュメントが最後にレビューされた日時が付記しており、そのドキュメンテーション集のメタデータがそのドキュメントに例えば3ヶ月手がつけられていない場合に、eメールでリマインダーを送ることになる。(239p)

今回の活動ではチームメンバほぼ全員でドキュメントの要不要をレビューしていきましたが、全員での確認が難しいほどの規模のチームになるとそのような確認方法は現実的に難しくなっていくと思いますし、時間を取って確認していくのは議論になった際の効率は良い反面、全員の時間が同期的に取られてしまうというデメリットがあることも事実です。

不要なドキュメントの洗い出しやドキュメントが"生き"ているかの確認を上記引用したような形である程度仕組み化できれば、ドキュメントの鮮度を保つ活動を効率的に進められるかもしれません。

以上、できるだけ効率的にドキュメントの鮮度を保つ活動をしていきたいと思った話でした。