明日から始める持続可能なドキュメンテーション戦略 / Sustainable Documentation Strategies: Documentation as a Product

2024-07-09 Platform Engineering Kaigi 2024
https://www.cnia.io/pek2024/

Transcript

1. 2024-07-09 Platform Engineering Kaigi 2024 @akitok 明日から始める持続可能な ドキュメンテーション戦略: Documentation as a Product
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. © CADDi Inc. 3 経験・データを資産化し 企業変革を支えるプラットフォーム Drawer What’s CADDi ?
4. 今日のテーマ • 話すこと ◦ 技術ドキュメントの継続的な運用 • （あまり）話さないこと ◦ ロジカルライティング ◦ テクニカルライティング
5. Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに
6. Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに
7. CADDi Platform チームの話 • CADDi Platform チーム ◦ 2021年7月に発足 ◦ Mission「開発組織のポテンシャルを解放する」 ◦ Platform チームの基本的な役割の考え方は チームトポロジーの定義と同じ ◦ Stream aligned team が自律的に仕事を届けられる ようにする ◦ 組織拡大に伴い、Security、CTOO、アーキテクト、 SRE など役割分担も進む
8. CADDi Platform チームの話 • チーム変遷 エンジニアの数も3年で3倍に！
9. 組織成長と共に膨らむドキュメントたち • 3年で組織もプロダクトも急速に成長し、Platform も追従・並走 そして 膨大な開発者向けドキュメント が... ◦ でも、ちゃんと使われてる？ ▪ 権限申請いつも質問きちゃうな... ▪ あれ？ Standard に準拠していない実装が...？ ▪ 問い合わせきたけど、 このドキュメント何だっけ... ? 開発ポリシー Log Standard Tracing Standard 権限申請 Terraform Guideline Service Mesh 導入ガイド GitHub Actions Guideline Monitoring Standard 踏み台サーバ 利用方法
10. • 頑張っているが、課題はたくさん ◦ ユーザーがたどりつけない ▪ 検索しても、ホームから追っても辿り着けず、結局人に聞く ◦ 最新化されていない ▪ 最終更新が古く、今も有効か分からない ▪ デッドリンクがある ◦ 構造や粒度や質がバラバラ ▪ 手順はあるけど、前提が書いていない ▪ 設計書はあるけど、構成図が見当たらない 組織成長と共に膨らむドキュメントたち
11. Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに
12. Documentation as a Product • Platform as a Product ◦ also, Documentation as a product • ドキュメントはなぜ重要？ ◦ Platform のことを知って欲しいから？ ➢ No ! 🙅 • 開発者が自律的に仕事を届けられるようにするため • プロダクトも開発者も変化する • Platform もドキュメントも、ユーザーである開発者の ニーズ変化に対応する必要がある
13. Documentation as a Product • ドキュメントはゴールデンパスの一部でもある 「道を照らす: プラットフォーム エンジニアリング、ゴールデンパス、セルフサービスのパワー」より引用 https://cloud.google.com/blog/ja/products/application-development/golden-paths-for-engineering-execution-consistency
14. Documentation as a Product *1 https://www.zoominsoftware.com/ebooks-success-stories/the-state-of-self-service-content-experiences • 調査会社 Frost & Sullivan の 2021 年のレポート (*1) ◦ ユーザーが情報を探している間に、無関係あるいは古いドキュメントを 閲覧している時間は 40 % ◦ 84 % のユーザーがドキュメントポータルの使用体験が悪ければ、他のブ ランドに切り替えると回答
15. Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに
16. ドキュメント改善への道 - 前提と準備 • ドキュメント改善プロジェクトを開始 ◦ でも、どこから始めたら... ▪ Confluence で作成している膨大な数のドキュメント • 人海戦術するにはつらい ▪ メンテナンスすべきドキュメントはどれ？ • 品質悪そうなものから手をつけたいが、果たして... ◦ 闇雲に取り組まず、先人たちの知恵を借りよう！ ▪ いくつか書籍を読み、チームメンバー全員の 認識やモチベーションを揃える
17. • 特に影響を受けた1冊 ◦ 「ユーザーの問題解決とプロダクトの成功を導く 　エンジニアのためのドキュメントライティング」 ▪ Platform… ? • ユーザーは開発者 • プロダクトはプラットフォームそのもの Platform as a product ➢ 我々が求めているテーマはまさにこれでは？ ドキュメント改善への道 - 前提と準備
18. • そもそも良いドキュメントって何？ ◦ 品質が良いこと？でもドキュメントの品質って？ 機能品質 構造品質 (3C) • アクセシビリティがあること • 目的があること • 見つけやすいこと • 正確なこと • 完全であること • Clear (明確な) • Concise (簡潔な) • Consistent (一貫している) ドキュメント改善への道 - 前提と準備 ドキュメントの目的やゴールが 達成されているかどうか ドキュメント自体がうまく書かれてい るか、うまく構成されているか
19. • 機能品質 vs 構造品質 ◦ 機能品質と構造品質、どちらがより重要？ ➢ 機能品質の達成、つまり「目的やゴールの達成」がより重要 ➢ 構造品質がどんなに良いドキュメントでも、目的やゴールが達成されず、読 者に価値を与えていないのであれば、認知負荷を増やしているだけ ドキュメント改善への道 - 前提と準備 ドキュメントの目的やゴールが 達成されているかどうか ドキュメント自体がうまく書かれてい るか、うまく構成されているか 機能品質 構造品質
20. • 機能品質・構造品質共に高いドキュメントを用意できたら OK ? ◦ No! 🙅 ◦ どんなに品質が良いドキュメントでも徐々にドキュメントは腐る ▪ 使っている技術の非推奨化、無効化 • 妙だな... XXX は 1 年前に非推奨になったはずだが... • 手順通りに実行したのに、知らないエラーが... ▪ メンテナーの不在化 • うーん、分からないことがあったから、書いた人に聞こ... って、この人もういないじゃん？！ ➢ 継続的な改善の営みが必要 🙆 ドキュメント改善への道 - 前提と準備
21. ドキュメント改善への道 - ドキュメントのライフサイクル 作成 レビュー 運用 品質担保は作成とレビューのステップで行う
22. ドキュメント改善への道 - 品質担保のためのポリシー定義 “ドキュメンテーションを書く際にエン ジニアがやってしまう間違いで最も重 大なものは、ドキュメンテーションを 自分のためだけに書くことである。” “代わりに、ドキュメントを書き始める 前に、（正式に、あるいは略式に）自 分のドキュメントが満足させる必要の ある対象読者を特定するべきだ。” 「Googleのソフトウェアエンジニアリング」 10.5 ドキュメンテーションの類型 より引用 “一般に、ドキュメントは唯一無二の目 的を持ち、それを貫き通すべきだ。API が1つのことをやり、それをうまくやる べきであるのと全く同様に、1つのド キュメント内で複数のことをやろうと するのは避けるべきだ。” 「Googleのソフトウェアエンジニアリング」 10.4 対象読者を認識せよ より引用 • 機能品質をまず考える ◦ ドキュメントの想定読者とゴールを捉え、類型化することが重要
23. ドキュメント改善への道 - 品質担保のためのポリシー定義 • ドキュメントタイプを定義し、類型化する ） コンセプトドキュメント • コンセプトを示す技術説明。実装は含まな い。 ◦ Internal ツールの概要 ◦ Log Standard Traceability Concept デザインドキュメント • 設計書。設計上のトレードオフと決定、考慮 事項等が含まれる。 ◦ Internal ツールの Design Doc 手順書 • ツールのインストールやサービスの設定など 目的を達成するための方法が記載される。 ◦ 踏み台サーバへのアクセス手順 ◦ hotfix リリース手順 ランディングページ • ユーザーが必要な情報にたどり着きやすいよ うにガイドする。 ◦ プロジェクトのポータルページ
24. ドキュメント改善への道 - 品質担保のためのポリシー定義 手順書 • ツールのインストールやサービスの設定など 目的を達成するための方法が記載される。 ◦ 踏み台サーバへのアクセス手順 ◦ hotfix リリース手順 開発者が、Platform チームが提供し ている仕組みの特定の手順を実行す ることで、どんな課題を解決出来る のか理解でき、実際に解決に導ける こと • 類型化したドキュメントの想定読者とゴールを定める
25. • ドキュメントタイプごとに テンプレートを用意 ◦ 構造品質をフォローする ◦ レビューもしやすい ◦ テンプレートでラベルを付与して、 一括で検索しやすくする ドキュメント改善への道 - 品質担保のためのポリシー定義
26. ドキュメント改善への道 - 品質担保のためのポリシー定義 作成 レビュー 運用 • ドキュメント タイプの定義 • 想定読者と ゴールの設定 • テンプレート
27. • レビューポリシーの策定 ▪ 機能品質・構造品質を担保 するためのチェックリスト を作る ➢ レビュー品質の属人性を 下げる ドキュメント改善への道 - 品質担保のためのポリシー定義
28. • レビューフローの策定 ◦ ページがレビュー中であることが分かるようにする ▪ Confluence の機能でステータスを変更する ◦ Slack のレビューチャンネルで依頼 ▪ 依頼で特定のスタンプを送る ▪ レビューポリシーが表示される ▪ レビュワーはレビューポリシーを 用いてレビューする ドキュメント改善への道 - 品質担保のためのポリシー定義
29. ドキュメント改善への道 - 品質担保のためのポリシー定義 作成 レビュー 運用 • レビューポリシー • レビューフロー • ドキュメント タイプの定義 • 想定読者と ゴールの設定 • テンプレート
30. ドキュメント改善への道 - 品質担保のためのポリシー定義 作成 レビュー 運用 • レビューポリシー • レビューフロー 品質が良いドキュメント を腐らせないために、 継続的な改善活動を行う • ドキュメント タイプの定義 • 想定読者と ゴールの設定 • テンプレート
31. ドキュメント改善への道 - 継続運用のためのポリシー定義 • メンテナンスポリシーを定義 ◦ 定期的なドキュメントメンテナンスの仕組み化を図る ▪ ドキュメントの量が膨大 • どこから手をつけたら... • いつ手をつけたら... ◦ 以下の2つのメトリクスを指標として追うことに ▪ ドキュメントの鮮度 ▪ ドキュメントの有効性
32. • ドキュメントの鮮度 ◦ ドキュメントの情報が最新でなければ、開発者に負担が増える ◦ そこでチームでは鮮度低下を判断する指標を以下のように定義した ▪ ドキュメントの最終更新日から一定期間を経過し、正確ではなく なった情報が記載されたままになっている ▪ ドキュメントのメンテナーが不在となり、メンテナンス機会が失わ れている ▪ ページ内の情報は正しいが、デッドリンクが含まれることで、ペー ジ全体の整合性や正しさが確認できなくなっている ドキュメント改善への道 - 継続運用のためのポリシー定義
33. • ドキュメントの有効性 ◦ ドキュメントの品質が良かったとしても、想定読者に利用されていない ドキュメントは価値を生み出していない ◦ そこでチームでは有効性低下を示唆する指標として以下を定義した ▪ ユーザー（＝想定読者）に閲覧されていない ドキュメント改善への道 - 継続運用のためのポリシー定義 → このようなドキュメントをリストアップして、メンテナンスする
34. ドキュメント改善への道 - まとめ 作成 レビュー 運用 • テンプレート • 想定読者とゴール の設定 • レビューポリシー • レビューフロー • 定期メンテナンス ◦ リストアップ ◦ メンテナンス 機能品質と構造品質を担保 鮮度と有効性を担保 • ドキュメント タイプの定義 • 想定読者と ゴールの設定 • テンプレート
35. Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに
36. いざ運用実践 - ROI 高いページから取り組む • いきなり各ページのメンテナンスに踏み込む前に、ROI の高いページ を先に取り組む ◦ ここでの ROI が高いとは？ ▪ ページのアクセス導線上重要なページ ➢ ランディングページ ▪ 頻繁に利用されるページ ➢ 閲覧数が多いページ ➢ よく質問されるページ
37. • ポータルのランディングページを修正して、導線設計を見直す いざ運用実践 - ROI 高いページから取り組む
38. • 技術ごとのランディングページを修正して、導線設計を見直す いざ運用実践 - ROI 高いページから取り組む Templateにより網羅性・統一性を担保 Example
39. • 頻繁に利用されるページ ◦ 閲覧数が多いページ ◦ よく質問されるページ ➢ 権限申請 • 入社・チーム異動時など毎月使われる ➢ 一時的な権限昇格を行うツール • 開発作業に伴って頻繁に利用される いざ運用実践 - ROI 高いページから取り組む
40. • 定期的なドキュメントメンテナンスの仕組み ◦ 鮮度低下および有効性低下が見られるドキュメントを定期的にメンテナ ンスする ▪ リストアップとメンテナンスの 2 Step ➢ リストアップはツールで自動化（月1回） ◦ 指定した条件に該当するドキュメントを TSV 出力 ➢ メンテナンスは手動で実施（毎週30分固定） ◦ TSV を基に作成したスプレッドシートで、作業分担・ ステータス管理 ◦ 時間枠を固定することで、徐々に改善を行う いざ運用実践 - 定期メンテナンス
41. いざ運用実践 - 定期メンテナンス
42. • 鮮度低下への対応 ◦ リストアップ ▪ 条件: ドキュメントの最終更新日から半年経過している ◦ メンテナンス ▪ ドキュメント所有者の確認 ➢ 無効なユーザーだったら、内容を確認し、自分自身を所有者にする ▪ リンクの確認 ➢ デッドリンクがあれば、代替可能なリンクがないか調査する ▪ 非推奨の確認 ➢ 既に非推奨な内容があれば、内容のアップデート、もしくはドキュメン ト自体のアーカイブを検討する いざ運用実践 - 定期メンテナンス
43. • 有効性低下への対応 ◦ リストアップ ▪ 条件: 直近 60 日間の閲覧数が 1 件以下である ◦ メンテナンス ▪ 以下のチェックリストを用いて、閲覧数低下の原因を探る ➢ 参照されることを想定している組織に周知が漏れていないか ➢ ランディングページから辿れないようになっていないか ➢ ユーザーの閲覧行動に規則性・季節性があり、閲覧数の増減が一過性の ものではなかったか ➢ など いざ運用実践 - 定期メンテナンス
44. 運用からのフィードバックループ • 気付いたことから繰り返し改善 ◦ 時間は有限なので、ROI も意識したい ➢ 鮮度チェックリストにも閲覧数を表示して、閲覧数は多いが鮮度が 低いものから手をつけるように ◦ 毎週30分の時間枠では時間が足りない ➢ 修正量が多いものはチケット切って、スプリント計画にいれる ◦ ページ更新により全体整合性が失われる ➢ 特にページアーカイブするときは、被リンクページがあれば、 それも含めて更新を行う
45. • 気付いたことから繰り返し改善 ◦ 英語ドキュメントの構成がバラバラ ➢ ページごと日英分けるパターンと、1ページに日英併記するパターン が混合していたが、後者のパターンでテンプレートを統一 ◦ 毎回の修正量・作業時間が減ってきた ➢ 毎週30分実施から、頻度や時間数を減らす 運用からのフィードバックループ
46. Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに
47. 効果と今後 - 1.5ヶ月のメンテナンスを経て • ドキュメント数削減！ ◦ Before: 199 記事 → After: 158 記事 (21%減) ▪ 検索ノイズは確実に減らせている • 多く改善のきっかけになる ◦ 既に非推奨・無効となっていた情報の更新が多くできた ▪ 既に移行済みで、推奨していない旧ミドルウェアの資料 ▪ SaaS に関する古い契約・Plan 情報 ➢ ドキュメントにここまで書いてあるとは分かっていないまま、 メンテが行き届いておらず、ミスリードしているものが多くある
48. 効果と今後 - ドキュメント改善プロジェクトを経て • Platform チームのマインド変化 ◦ ドキュメントに関する認識・モチベーションのすり合わせも副次的に 大きな効果があった ◦ 自分が執筆していないドキュメントでも Platform チームのプロダクト として、オーナーシップを持ちやすくなる ▪ キャッチアップにもなる ◦ レビューポリシーによる品質の安定化 ▪ 「それぞれの価値観で主観的にレビューする」から 「同じ規範・品質水準に基づいて客観的にレビューする」へ
49. 効果と今後 - ユーザーインタビュー • ユーザーインタビューからポジティブな声 ◦ ランディングページ辿りやすい ◦ 知らないドキュメントの存在に初めて気付いた...！ ▪ 今までついググってしまっていたが、社内により具体的な知見があ ることに気付けた • 一方で、以下のような意見も ◦ 開発者向けポータルのトップページの存在を知らなかった ◦ 開発者のオンボーディング資料からの導線も改善できそう
50. 効果と今後 - さらに挑戦 • 機械的な作業の自動化 ◦ リンクチェッカー、リンター ◦ レビューフローの自動化（Pull Requestスタイルでのレビューなど） ◦ メンテナンス契機の通知の自動化 ◦ 特定階層配下のドキュメントにラベルを自動付与
51. 効果と今後 - さらに挑戦 • ドキュメントの利用動向を参考に、開発者の利用体験向上を図る ◦ ツール提供・開発による開発者の作業負荷軽減 ▪ よく利用される How-to ページの自動化ツールの開発と提供 ▪ よく利用されるチェックリスト形式ドキュメントのプロセス自動化 ◦ さらなる導線改善による開発者の認知負荷軽減 ▪ セットで読まれるドキュメントのパッケージング ▪ ChatBot などインタフェースの検討 ▪ 開発プロセスに応じて、ドキュメントをサジェストする仕組み
52. 効果と今後 - さらに挑戦 • ドキュメントの有効性をどう測る？どう上げていく？ ◦ 現在は手がかりとして閲覧数を指標としているが、閲覧数が低いことがだ けで有効性を測ることは出来ない ▪ 閲覧数 0 には、「見る必要がなかった」「他のドキュメントや情報 を見て解決した」「探したが見つからなかった」など様々な要因が含 まれるので、原因分析が必要 ➢ 定量的な情報だけで、ユーザーにとっての有効性を測ることは難しい ◦ 定性的なデータ収集も増やす ▪ アンケート、ユーザーインタビューなどの継続的な実施 ▪ Slack で記事 URL を検索して、インサイトを得る
53. Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに
54. おわりに • ドキュメント運用の仕組み化を明日から始めよう ◦ 一過性のものではなく、継続的な活動を ◦ 利用しているドキュメントシステムに合わせて、ドキュメントのメトリ クスを計測して、きっかけを作ろう • Platform as a Product. Also, Documentation as a product. ◦ 開発者のニーズに合わず価値を提供できないドキュメントはいらない ◦ 定量評価だけではユーザーニーズを真に捉えきれない ▪ ユーザーインタビューなどを通して、ニーズを集めよう