ドキュメント改善の背景

CADDi では組織もプロダクトも急成長しており、Platform もそれに追従しながら開発のスタンダード・基盤作りを行い、開発者向けのドキュメントを多く作成してきました。そういった中、ドキュメントに対する以下のような課題が見えてきました。

ユーザーがたどり着けない
最新化されていない
構造や粒度や質がバラバラ

いくら重要で価値があるドキュメントがあっても、適切に利用されていないのでは意味がありません。そこで、2024 年 3 月からドキュメントの再構成やポリシー定義化を行い、5 月から実際にドキュメントメンテナンスを始めました。その活動の詳細は、7 月に Platform Engineering Kaigi 2024 というイベントで、お話しましたので以下の資料や動画をご覧ください。

caddi.tech speakerdeck.com

ドキュメントメンテナンスをやってみた結果

現在も継続してドキュメントメンテナンスを行っていますが、ここまでの結果を紹介します。

ドキュメント数の削減

ドキュメント改善を開始した時点で管理対象ドキュメントは 199 ページありましたが、現在は 147 ページと、約 26 % もの管理ドキュメントを削減できました。具体的には 47 ページのドキュメントをアーカイブし、検索ノイズや管理対象ドキュメントは減らすことが出来ました。

ドキュメントのアクセス数の変化

各月のドキュメントアクセス総数の変化は以下の通りです。*1

初回のドキュメントメンテナンスが完了したのが、2024 年 5 月末ですので、2024 年 6 月は有意な上昇傾向がありそうに見えますが、それ以降は単純な上昇傾向ではなくほぼ横ばいです。また、各月の閲覧数の多いドキュメントをランキングで見ると、以下のような傾向も見られました。

当月に開発者に対して更新通知・説明がされたページのアクセス数が有意に増える。
新サービスの開発・リリースが多い時期に、アナウンスがなくとも Production Readiness Checklist や Log Format などのアクセス数が有意に増える。
ランディングページのアクセス数が相対的に低い。

仮説

収集可能な定量データから得られた情報は少ないですが、以下のような仮説が考えられます。

ドキュメントメンテナンスを実施しているが、アクセス総数が横ばいになった
→ 不要なページ数が減って、検索ノイズが減った
エンジニアの数は毎月増えているがアクセス総数が比例していない
→ オンボーディングの動線が悪い可能性がある
ランディングページのアクセス数が相対的に低いが、開発者が適宜必要なドキュメントを閲覧しようとしている
→ 多くのユーザーは検索やブックマーク・リンクなどからアクセスしており、ランディングページの認知が低い

ドキュメントメンテナンス活動のふりかえり

改善自体の評価とは別に、チームのドキュメントメンテナンス活動のふりかえりも進めました。

毎月のメンテナンス対象ドキュメント数の推移

2024 年 5 月〜 12 月の活動でチェックしたドキュメントの総数は延べ 402 ページ、修正したドキュメントの総数は、延べ 132 ページでした。ドキュメントの鮮度や有効性が低下したと見られるドキュメントに対して毎月対応した量をグラフにしてみると以下のようでした。

やはり運用開始した序盤はドキュメント総数もかなりの量ですが、徐々に作業量も落ち着いてきています。作業時間としても、開始当初は毎週 1 時間 × 4 人= 月 40 時間で実施していましたが、現在は隔週 1 時間 × 3 人 = 月 6 時間で済んでおり、85 %省力化が進んでいます

チーム内でのふりかえり

チームのふりかえりとして、ドキュメント改善活動の KPT も実施しました。

Keep

メンテ対象のドキュメントが徐々に減ることで、毎月の業務を圧迫することなく安定して運用できている
初見のドキュメントを読んで、結果的にキャッチアップにもなった
鮮度低下へのアクションは今まで通り継続出来れば良さそう

Problem

有効性低下へのアクションについて継続改善は出来ているが効果を測れていない
- ドキュメント全体のアクセス数が横ばい
閲覧されていないドキュメントはリストアップ出来ているが、もっと閲覧されるべきだが閲覧されていないドキュメントのリストアップが出来ていない
- そもそも誰にいつ読んでほしいドキュメントなのか、整理されていない
Platform チーム管理外の開発に関わるドキュメントも多くある
Tips のようなドキュメントへの対応が難しい

Try

Tips 資料がドキュメントメンテナンスの対象になったら、そのまま修正を行うのではなく、ドキュメントタイプや読者、ゴールの明確化を最初に実施する
改めて現時点の開発者のドキュメント課題を訊いてみる

現時点の開発者のドキュメント課題とは何なのか？

今回のドキュメントメンテナンス活動は一定の成果はあったものの、ドキュメント改善の検討をし始めた 2024 年 3 月時点とは異なる以下のような変化が起きています。

プロダクトの成長速度や開発者が増すペースが上がっている
- 今までよりさらにローコンテクストに伝える必要が出てきた
- また、英語話者も増えている
横断組織が増え、CTO Office や Product Security Team、QA Team が提供する開発者向けドキュメントも増えてきた

こういった背景の中で、開発者向けにアンケートを実施しました。その結果、以下のような課題があることが分かってきました。

特にプロジェクトの開始時に何のドキュメントをどの順序で見るべきか迷う
開発に必須となるポリシーをドキュメントでカバーしきれていない
オンボーディングドキュメントが最新化されていない
検索が弱いため、ドキュメントの存在を認知できない（元からある課題）

以上から、開発のライフサイクルに沿ったドキュメント体系になっていないことが大きな課題のひとつだと判断しました。この課題を解決するために、以下のような Step で対応することを検討しています。

必要な資料の整理
開発のライフサイクルにおいて、いつどのような資料が必要なのか整理します。
資料の導線設計
オンボーディングや開発着手時に参照するドキュメントのインデックスを整理し、ガイダンスを用意します。
不足している資料の作成
不足していると判明したドキュメントを、横断組織が中心となり、作成の計画を進めます。
鮮度や有効性のメンテナンス運用の水平展開
ここまでの Step で開発ライフサイクルに沿ったドキュメント体系の整理は完了しているので、ここから改めて鮮度低下や有効性低下が発生しているドキュメントを抽出し、メンテナンスする運用にしていきます。

終わりに

本記事では、Platform Engineering Kaigi 2024 で登壇した開発者向けドキュメントの改善の後日談について書かせていただきました。開発者向けのドキュメント改善に向けてはまだまだ道半ばです。ドキュメントの改善を通じた開発者体験の向上により、開発者のポテンシャル解放を推し進めていく、そんな仕組み作りをしていきたいと考えています。

*1:私たちはドキュメント管理システムに Confluence を用いているので、Confluence API で Page Views 数を取得しました。