持続可能なドキュメント運用のリアル: 1年間の成果とこれから

2025-04-23
ドキュメントの鮮度を維持する「しくみ化」の方法
CADDi、DMM.com、IVRyの実践例から
https://levtechlab.connpass.com/event/346655/

Transcript

1. 2025-04-23 @akitok 持続可能なドキュメント運用のリアル: 1年間の成果とこれから
2. About me • Akito Kobayashi ◦ X(Twitter) / @akitok_ ◦ 2010-04 ~ Infra / Backend / DevOps Engineer at 通信系 SIer ◦ 2020-07 ~ Platform SRE at ファッション系ECサイト ◦ 2024-01 ~ Platform チーム at CADDi
3. 製造業AIデータ プラットフォーム CADDi 経験‧データを資産化する
4. Agenda 1. CADDi Platform チームの話 2. 1年間ドキュメントメンテナンスを実施した成果と考察 3. 開発者へのヒアリングと改善活動 4. おわりに
5. Agenda 1. CADDi Platform チームの話 2. 1年間ドキュメントメンテナンスを実施した成果と考察 3. 開発者へのヒアリングと改善活動 4. おわりに
6. CADDi Platform チームの話 • CADDi Platform チーム ◦ 2021年7月に発足 ◦ Mission「開発組織のポテンシャルを解放する」 ◦ Platform チームの基本的な役割の考え方は チームトポロジーの定義と同じ ◦ Stream aligned team が自律的に仕事を届けられる ようにする ◦ 組織拡大に伴い、Security、CTOO、アーキテクト、 SRE など役割分担も進む
7. 組織成長と共に膨らむドキュメントたち • 3年で組織もプロダクトも急速に成長し、Platform も追従・並走 そして 膨大な開発者向けドキュメント が... ◦ でも、ちゃんと使われてる？ ▪ 権限申請いつも質問きちゃうな... ▪ あれ？ Standard に準拠していない実装が...？ ▪ 問い合わせきたけど、 このドキュメント何だっけ... ? 開発ポリシー Log Standard Tracing Standard 権限申請 Terraform Guideline Service Mesh 導入ガイド GitHub Actions Guideline Monitoring Standard 踏み台サーバ 利用方法
8. • 頑張っているが、課題はたくさん ◦ ユーザーがたどりつけない ▪ 検索しても、ホームから追っても辿り着けず、結局人に聞く ◦ 最新化されていない ▪ 最終更新が古く、今も有効か分からない ▪ デッドリンクがある ◦ 構造や粒度や質がバラバラ ▪ 手順はあるけど、前提が書いていない ▪ 設計書はあるけど、構成図が見当たらない 組織成長と共に膨らむドキュメントたち
9. ドキュメント改善プロジェクト爆誕 • 2024年4月頃から、ドキュメントの改善活動を開始 • その営みを Platform Engineering Kaigi 2024 (PEK2024) で発表 • 今日はこの後日談を話します
10. PEK2024 の資料から ドキュメント改善の仕組み化 作成 レビュー 運用 • レビューポリシー • レビューフロー • 定期メンテナンス ◦ リストアップ ◦ メンテナンス 機能品質と構造品質を担保 鮮度と有効性を担保 • ドキュメント タイプの定義 • 想定読者と ゴールの設定 • テンプレート
11. 作成 レビュー 運用 • ドキュメント タイプの定義 • 想定読者と ゴールの設定 • テンプレート • レビューポリシー • レビューフロー • 定期メンテナンス ◦ リストアップ ◦ メンテナンス 機能品質と構造品質を担保 鮮度と有効性を担保 今日は ここの話！ PEK2024 の資料から ドキュメント改善の仕組み化
12. • 定期的なドキュメントメンテナンスの仕組み ◦ 鮮度低下および有効性低下が見られるドキュメントを 定期的にメンテナンスする ▪ リストアップとメンテナンスの 2 Step ➢ リストアップはツールで自動化（月1回） ◦ 指定した条件に該当するドキュメントを TSV 出力 ➢ メンテナンスは手動で実施（毎週30分固定） ◦ TSV を基に作成したスプレッドシートで、作業分担・ ステータス管理 ◦ 時間枠を固定することで、徐々に改善を行う 定期メンテナンス
13. • メンテナンスルール 定期メンテナンス リストアップ • 条件: 最終更新日から半年経過 メンテナンス • ドキュメント所有者の確認 ◦ 無効なユーザーだったら、内容を 確認し、自分自身を所有者にする • リンクの確認 ◦ デッドリンクは、代替可能なリン クがないか調査する • 非推奨の確認 ◦ 非推奨な内容であれば、内容の アップデート、もしくはドキュメ ント自体のアーカイブを検討する リストアップ • 条件: 直近 60 日の閲覧数が 1 以下 メンテナンス • 以下のチェックリストを用いて、閲覧数 低下の原因を探る ◦ 周知が漏れていないか ◦ ランディングページから辿れないよ うになっていないか ◦ ユーザーの閲覧行動に規則性・季節 性があり、閲覧数の増減が一過性の ものではなかったか … など 鮮度のメンテナンス 有効性のメンテナンス
14. Agenda 1. CADDi Platform チームの話 2. 1年間ドキュメントメンテナンスを実施した成果と考察 3. 開発者へのヒアリングと改善活動 4. おわりに
15. 成果と考察 • ドキュメント数の削減 約 27 % の管理ドキュメントを削減し、検索ノイズは確実に減った 27% 削減 199 144
16. 成果と考察 • アクセス数の変化 ◦ 初回メンテを行った直後の月は有意な上昇傾向があるが、それ以降は横ばい ➢ 不要なページ数が減って、検索ノイズが減り、不要な回遊が減った？ ◦ エンジニアの数は毎月増えているがアクセス総数が比例していない ➢ オンボーディングの動線が悪い可能性がある
17. 成果と考察 • ドキュメントの閲覧数ランキングを見ると、以下のような傾向 ◦ 開発者に対して更新通知・説明がされたページのアクセス数が、 その月に有意に増える。 ◦ 新サービスの開発・リリースが多い時期に、Log Format など開発に 必要なドキュメントのアクセス数が有意に増える。 ◦ ランディングページのアクセス数が相対的に低い。 ➢ 多くのユーザーは検索やブックマーク・リンク、あるいは周知など を起点にアクセスしており、ランディングページの存在が認知され ていない。
18. Agenda 1. CADDi Platform チームの話 2. 1年間ドキュメントメンテナンスを実施した成果と考察 3. 開発者へのヒアリングと改善活動 4. おわりに
19. 開発者を取り巻く環境の変化 • 一定の成果はあったが、ドキュメント改善活動を始めた当初とは 異なる変化も生まれている。 ◦ プロダクトの成長速度や開発者が増すペースが上がっている ▪ 今までよりさらにローコンテクストに伝える必要が出てきた ▪ また、英語話者も増えている ◦ 横断組織が増え、開発者向け に提供されるドキュメントが 増えてきた
20. 開発者へのヒアリング • そこで、開発者向けアンケートを実施したところ、 ドキュメントに対する様々な声が... 誰かに聞かないとドキュメントを 見つけられない プロジェクトを始めるときのドキュメントや ツール一式がまとまって欲しい 開発プロセスやデリバリにおける オンボーディングが弱い 開発の進め方に関する指針が欲しい システム全体構成を理解・説明するのに 苦労する 開発環境構築からつまづく
21. 開発者へのヒアリング • 以下の課題だと再整理し、さらなる改善へ 誰かに聞かないとドキュメントを 見つけられない プロジェクトを始めるときのドキュメントや ツール一式がまとまって欲しい 開発プロセスやデリバリにおける オンボーディングが弱い 開発の進め方に関する指針が欲しい システム全体構成を理解・説明するのに 苦労する 開発環境構築からつまづく 開発のライフサイクルに沿ったドキュメント体系の 整理がされていない ドキュメントにたどり着くのが難しく、 認知されていない
22. さらなる改善への道のり 資料の再整理 鮮度や有効性のメ ンテナンス運用の 水平展開 不足している資料 の作成 資料の導線設計 とアナウンス オンボーディング や開発着手時に参 照するドキュメン トのインデックス を整理し、ガイダ ンスを用意し、周 知する 不足していると判 明したドキュメン トを、横断組織が 中心となり、作成 の計画と実施を行 う 鮮度低下や有効性 低下が発生してい るドキュメントを 抽出し、メンテナ ンスする運用を始 める 開発のライフサイ クルにおいて、い つ・どのような資 料が必要なのか整 理する • 以下のステップで改善進行中💪
23. さらなる改善への道のり 資料の再整理 鮮度や有効性のメ ンテナンス運用の 水平展開 不足している資料 の作成 資料の導線設計 とアナウンス オンボーディング や開発着手時に参 照するドキュメン トのインデックス を整理し、ガイダ ンスを用意し、周 知する 不足していると判 明したドキュメン トを、横断組織が 中心となり、作成 の計画を行う 鮮度低下や有効性 低下が発生してい るドキュメントを 抽出し、メンテナ ンスする運用を始 める 開発のライフサイ クルにおいて、い つ・どのような資 料が必要なのか整 理する • 以下のステップで改善進行中💪 ADR Design Doc Coding Guide QA Guide Production Readiness Checklist Security Checklist Monitoring Guide Monitoring Guide PRD Incident Management Machine Setup Guide Branch Rule Release Guide
24. さらなる改善への道のり 資料の再整理 鮮度や有効性のメ ンテナンス運用の 水平展開 不足している資料 の作成 資料の導線設計 とアナウンス オンボーディング や開発着手時に参 照するドキュメン トのインデックス を整理し、ガイダ ンスを用意し、周 知する 不足していると判 明したドキュメン トを、横断組織が 中心となり、作成 の計画を行う 鮮度低下や有効性 低下が発生してい るドキュメントを 抽出し、メンテナ ンスする運用を始 める 開発のライフサイ クルにおいて、い つ・どのような資 料が必要なのか整 理する • 以下のステップで改善進行中💪
25. 今ここ！ さらなる改善への道のり 資料の再整理 鮮度や有効性のメ ンテナンス運用の 水平展開 不足している資料 の作成 資料の導線設計 とアナウンス オンボーディング や開発着手時に参 照するドキュメン トのインデックス を整理し、ガイダ ンスを用意し、周 知する 不足していると判 明したドキュメン トを、横断組織が 中心となり、作成 の計画を行う 鮮度低下や有効性 低下が発生してい るドキュメントを 抽出し、メンテナ ンスする運用を始 める 開発のライフサイ クルにおいて、い つ・どのような資 料が必要なのか整 理する • 以下のステップで改善進行中💪
26. to be next… さらなる改善への道のり 資料の再整理 鮮度や有効性のメ ンテナンス運用の 水平展開 不足している資料 の作成 資料の導線設計 とアナウンス オンボーディング や開発着手時に参 照するドキュメン トのインデックス を整理し、ガイダ ンスを用意し、周 知する 不足していると判 明したドキュメン トを、横断組織が 中心となり、作成 の計画を行う 鮮度低下や有効性 低下が発生してい るドキュメントを 抽出し、メンテナ ンスする運用を始 める 開発のライフサイ クルにおいて、い つ・どのような資 料が必要なのか整 理する • 以下のステップで改善進行中💪
27. Agenda 1. CADDi Platform チームの話 2. 1年間ドキュメントメンテナンスを実施した成果と考察 3. 開発者へのヒアリング 4. おわりに
28. おわりに • ドキュメント運用の仕組み化を明日から始めよう ◦ 鮮度のメンテナンスは効果が見えやすい ◦ 有効性は定量評価が難しい ▪ ユーザーインタビューなどを通じて、根拠を集めよう ▪ 何をもって有効とするかは意志を込めよう