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

by akitok

Slide 1

Slide 1 text

2024-07-09 Platform Engineering Kaigi 2024 @akitok 明日から始める持続可能なドキュメンテーション戦略: Documentation as a Product

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

Slide 4

Slide 4 text

今日のテーマ ● 話すこと ○ 技術ドキュメントの継続的な運用 ● （あまり）話さないこと ○ ロジカルライティング ○ テクニカルライティング

Slide 5

Slide 5 text

Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに

Slide 6

Slide 6 text

Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに

Slide 7

Slide 7 text

CADDi Platform チームの話 ● CADDi Platform チーム ○ 2021年7月に発足 ○ Mission「開発組織のポテンシャルを解放する」 ○ Platform チームの基本的な役割の考え方はチームトポロジーの定義と同じ ○ Stream aligned team が自律的に仕事を届けられるようにする ○ 組織拡大に伴い、Security、CTOO、アーキテクト、 SRE など役割分担も進む

Slide 8

Slide 8 text

CADDi Platform チームの話 ● チーム変遷エンジニアの数も3年で3倍に！

Slide 9

Slide 9 text

組織成長と共に膨らむドキュメントたち ● 3年で組織もプロダクトも急速に成長し、Platform も追従・並走そして膨大な開発者向けドキュメントが... ○ でも、ちゃんと使われてる？ ■ 権限申請いつも質問きちゃうな... ■ あれ？ Standard に準拠していない実装が...？ ■ 問い合わせきたけど、このドキュメント何だっけ... ? 開発ポリシー Log Standard Tracing Standard 権限申請 Terraform Guideline Service Mesh 導入ガイド GitHub Actions Guideline Monitoring Standard 踏み台サーバ利用方法

Slide 10

Slide 10 text

● 頑張っているが、課題はたくさん ○ ユーザーがたどりつけない ■ 検索しても、ホームから追っても辿り着けず、結局人に聞く ○ 最新化されていない ■ 最終更新が古く、今も有効か分からない ■ デッドリンクがある ○ 構造や粒度や質がバラバラ ■ 手順はあるけど、前提が書いていない ■ 設計書はあるけど、構成図が見当たらない組織成長と共に膨らむドキュメントたち

Slide 11

Slide 11 text

Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに

Slide 12

Slide 12 text

Documentation as a Product ● Platform as a Product ○ also, Documentation as a product ● ドキュメントはなぜ重要？ ○ Platform のことを知って欲しいから？ ➢ No ! 🙅 ● 開発者が自律的に仕事を届けられるようにするため ● プロダクトも開発者も変化する ● Platform もドキュメントも、ユーザーである開発者のニーズ変化に対応する必要がある

Slide 13

Slide 13 text

Documentation as a Product ● ドキュメントはゴールデンパスの一部でもある「道を照らす: プラットフォームエンジニアリング、ゴールデンパス、セルフサービスのパワー」より引用 https://cloud.google.com/blog/ja/products/application-development/golden-paths-for-engineering-execution-consistency

Slide 14

Slide 14 text

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 % のユーザーがドキュメントポータルの使用体験が悪ければ、他のブランドに切り替えると回答

Slide 15

Slide 15 text

Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに

Slide 16

Slide 16 text

ドキュメント改善への道 - 前提と準備 ● ドキュメント改善プロジェクトを開始 ○ でも、どこから始めたら... ■ Conﬂuence で作成している膨大な数のドキュメント ● 人海戦術するにはつらい ■ メンテナンスすべきドキュメントはどれ？ ● 品質悪そうなものから手をつけたいが、果たして... ○ 闇雲に取り組まず、先人たちの知恵を借りよう！ ■ いくつか書籍を読み、チームメンバー全員の認識やモチベーションを揃える

Slide 17

Slide 17 text

● 特に影響を受けた1冊 ○ 「ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング」 ■ Platform… ? ● ユーザーは開発者 ● プロダクトはプラットフォームそのもの Platform as a product ➢ 我々が求めているテーマはまさにこれでは？ドキュメント改善への道 - 前提と準備

Slide 18

Slide 18 text

● そもそも良いドキュメントって何？ ○ 品質が良いこと？でもドキュメントの品質って？機能品質構造品質 (3C) ● アクセシビリティがあること ● 目的があること ● 見つけやすいこと ● 正確なこと ● 完全であること ● Clear (明確な) ● Concise (簡潔な) ● Consistent (一貫している) ドキュメント改善への道 - 前提と準備ドキュメントの目的やゴールが達成されているかどうかドキュメント自体がうまく書かれているか、うまく構成されているか

Slide 19

Slide 19 text

● 機能品質 vs 構造品質 ○ 機能品質と構造品質、どちらがより重要？ ➢ 機能品質の達成、つまり「目的やゴールの達成」がより重要 ➢ 構造品質がどんなに良いドキュメントでも、目的やゴールが達成されず、読者に価値を与えていないのであれば、認知負荷を増やしているだけドキュメント改善への道 - 前提と準備ドキュメントの目的やゴールが達成されているかどうかドキュメント自体がうまく書かれているか、うまく構成されているか機能品質構造品質

Slide 20

Slide 20 text

● 機能品質・構造品質共に高いドキュメントを用意できたら OK ? ○ No! 🙅 ○ どんなに品質が良いドキュメントでも徐々にドキュメントは腐る ■ 使っている技術の非推奨化、無効化 ● 妙だな... XXX は 1 年前に非推奨になったはずだが... ● 手順通りに実行したのに、知らないエラーが... ■ メンテナーの不在化 ● うーん、分からないことがあったから、書いた人に聞こ... って、この人もういないじゃん？！ ➢ 継続的な改善の営みが必要 🙆 ドキュメント改善への道 - 前提と準備

Slide 21

Slide 21 text

ドキュメント改善への道 - ドキュメントのライフサイクル作成レビュー運用品質担保は作成とレビューのステップで行う

Slide 22

Slide 22 text

ドキュメント改善への道 - 品質担保のためのポリシー定義 “ドキュメンテーションを書く際にエンジニアがやってしまう間違いで最も重大なものは、ドキュメンテーションを自分のためだけに書くことである。” “代わりに、ドキュメントを書き始める前に、（正式に、あるいは略式に）自分のドキュメントが満足させる必要のある対象読者を特定するべきだ。” 「Googleのソフトウェアエンジニアリング」 10.5 ドキュメンテーションの類型より引用 “一般に、ドキュメントは唯一無二の目的を持ち、それを貫き通すべきだ。API が1つのことをやり、それをうまくやるべきであるのと全く同様に、1つのドキュメント内で複数のことをやろうとするのは避けるべきだ。” 「Googleのソフトウェアエンジニアリング」 10.4 対象読者を認識せよより引用 ● 機能品質をまず考える ○ ドキュメントの想定読者とゴールを捉え、類型化することが重要

Slide 23

Slide 23 text

ドキュメント改善への道 - 品質担保のためのポリシー定義 ● ドキュメントタイプを定義し、類型化する）コンセプトドキュメント ● コンセプトを示す技術説明。実装は含まない。 ○ Internal ツールの概要 ○ Log Standard Traceability Concept デザインドキュメント ● 設計書。設計上のトレードオフと決定、考慮事項等が含まれる。 ○ Internal ツールの Design Doc 手順書 ● ツールのインストールやサービスの設定など目的を達成するための方法が記載される。 ○ 踏み台サーバへのアクセス手順 ○ hotﬁx リリース手順ランディングページ ● ユーザーが必要な情報にたどり着きやすいようにガイドする。 ○ プロジェクトのポータルページ

Slide 24

Slide 24 text

ドキュメント改善への道 - 品質担保のためのポリシー定義手順書 ● ツールのインストールやサービスの設定など目的を達成するための方法が記載される。 ○ 踏み台サーバへのアクセス手順 ○ hotﬁx リリース手順開発者が、Platform チームが提供している仕組みの特定の手順を実行することで、どんな課題を解決出来るのか理解でき、実際に解決に導けること ● 類型化したドキュメントの想定読者とゴールを定める

Slide 25

Slide 25 text

● ドキュメントタイプごとにテンプレートを用意 ○ 構造品質をフォローする ○ レビューもしやすい ○ テンプレートでラベルを付与して、一括で検索しやすくするドキュメント改善への道 - 品質担保のためのポリシー定義

Slide 26

Slide 26 text

ドキュメント改善への道 - 品質担保のためのポリシー定義作成レビュー運用 ● ドキュメントタイプの定義 ● 想定読者とゴールの設定 ● テンプレート

Slide 27

Slide 27 text

● レビューポリシーの策定 ■ 機能品質・構造品質を担保するためのチェックリストを作る ➢ レビュー品質の属人性を下げるドキュメント改善への道 - 品質担保のためのポリシー定義

Slide 28

Slide 28 text

● レビューフローの策定 ○ ページがレビュー中であることが分かるようにする ■ Conﬂuence の機能でステータスを変更する ○ Slack のレビューチャンネルで依頼 ■ 依頼で特定のスタンプを送る ■ レビューポリシーが表示される ■ レビュワーはレビューポリシーを用いてレビューするドキュメント改善への道 - 品質担保のためのポリシー定義

Slide 29

Slide 29 text

ドキュメント改善への道 - 品質担保のためのポリシー定義作成レビュー運用 ● レビューポリシー ● レビューフロー ● ドキュメントタイプの定義 ● 想定読者とゴールの設定 ● テンプレート

Slide 30

Slide 30 text

ドキュメント改善への道 - 品質担保のためのポリシー定義作成レビュー運用 ● レビューポリシー ● レビューフロー品質が良いドキュメントを腐らせないために、継続的な改善活動を行う ● ドキュメントタイプの定義 ● 想定読者とゴールの設定 ● テンプレート

Slide 31

Slide 31 text

ドキュメント改善への道 - 継続運用のためのポリシー定義 ● メンテナンスポリシーを定義 ○ 定期的なドキュメントメンテナンスの仕組み化を図る ■ ドキュメントの量が膨大 ● どこから手をつけたら... ● いつ手をつけたら... ○ 以下の2つのメトリクスを指標として追うことに ■ ドキュメントの鮮度 ■ ドキュメントの有効性

Slide 32

Slide 32 text

● ドキュメントの鮮度 ○ ドキュメントの情報が最新でなければ、開発者に負担が増える ○ そこでチームでは鮮度低下を判断する指標を以下のように定義した ■ ドキュメントの最終更新日から一定期間を経過し、正確ではなくなった情報が記載されたままになっている ■ ドキュメントのメンテナーが不在となり、メンテナンス機会が失われている ■ ページ内の情報は正しいが、デッドリンクが含まれることで、ページ全体の整合性や正しさが確認できなくなっているドキュメント改善への道 - 継続運用のためのポリシー定義

Slide 33

Slide 33 text

● ドキュメントの有効性 ○ ドキュメントの品質が良かったとしても、想定読者に利用されていないドキュメントは価値を生み出していない ○ そこでチームでは有効性低下を示唆する指標として以下を定義した ■ ユーザー（＝想定読者）に閲覧されていないドキュメント改善への道 - 継続運用のためのポリシー定義 → このようなドキュメントをリストアップして、メンテナンスする

Slide 34

Slide 34 text

ドキュメント改善への道 - まとめ作成レビュー運用 ● テンプレート ● 想定読者とゴールの設定 ● レビューポリシー ● レビューフロー ● 定期メンテナンス ○ リストアップ ○ メンテナンス機能品質と構造品質を担保鮮度と有効性を担保 ● ドキュメントタイプの定義 ● 想定読者とゴールの設定 ● テンプレート

Slide 35

Slide 35 text

Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに

Slide 36

Slide 36 text

いざ運用実践 - ROI 高いページから取り組む ● いきなり各ページのメンテナンスに踏み込む前に、ROI の高いページを先に取り組む ○ ここでの ROI が高いとは？ ■ ページのアクセス導線上重要なページ ➢ ランディングページ ■ 頻繁に利用されるページ ➢ 閲覧数が多いページ ➢ よく質問されるページ

Slide 37

Slide 37 text

● ポータルのランディングページを修正して、導線設計を見直すいざ運用実践 - ROI 高いページから取り組む

Slide 38

Slide 38 text

● 技術ごとのランディングページを修正して、導線設計を見直すいざ運用実践 - ROI 高いページから取り組む Templateにより網羅性・統一性を担保 Example

Slide 39

Slide 39 text

● 頻繁に利用されるページ ○ 閲覧数が多いページ ○ よく質問されるページ ➢ 権限申請 ● 入社・チーム異動時など毎月使われる ➢ 一時的な権限昇格を行うツール ● 開発作業に伴って頻繁に利用されるいざ運用実践 - ROI 高いページから取り組む

Slide 40

Slide 40 text

● 定期的なドキュメントメンテナンスの仕組み ○ 鮮度低下および有効性低下が見られるドキュメントを定期的にメンテナンスする ■ リストアップとメンテナンスの 2 Step ➢ リストアップはツールで自動化（月1回） ○ 指定した条件に該当するドキュメントを TSV 出力 ➢ メンテナンスは手動で実施（毎週30分固定） ○ TSV を基に作成したスプレッドシートで、作業分担・ステータス管理 ○ 時間枠を固定することで、徐々に改善を行ういざ運用実践 - 定期メンテナンス

Slide 41

Slide 41 text

いざ運用実践 - 定期メンテナンス

Slide 42

Slide 42 text

● 鮮度低下への対応 ○ リストアップ ■ 条件: ドキュメントの最終更新日から半年経過している ○ メンテナンス ■ ドキュメント所有者の確認 ➢ 無効なユーザーだったら、内容を確認し、自分自身を所有者にする ■ リンクの確認 ➢ デッドリンクがあれば、代替可能なリンクがないか調査する ■ 非推奨の確認 ➢ 既に非推奨な内容があれば、内容のアップデート、もしくはドキュメント自体のアーカイブを検討するいざ運用実践 - 定期メンテナンス

Slide 43

Slide 43 text

● 有効性低下への対応 ○ リストアップ ■ 条件: 直近 60 日間の閲覧数が 1 件以下である ○ メンテナンス ■ 以下のチェックリストを用いて、閲覧数低下の原因を探る ➢ 参照されることを想定している組織に周知が漏れていないか ➢ ランディングページから辿れないようになっていないか ➢ ユーザーの閲覧行動に規則性・季節性があり、閲覧数の増減が一過性のものではなかったか ➢ などいざ運用実践 - 定期メンテナンス

Slide 44

Slide 44 text

運用からのフィードバックループ ● 気付いたことから繰り返し改善 ○ 時間は有限なので、ROI も意識したい ➢ 鮮度チェックリストにも閲覧数を表示して、閲覧数は多いが鮮度が低いものから手をつけるように ○ 毎週30分の時間枠では時間が足りない ➢ 修正量が多いものはチケット切って、スプリント計画にいれる ○ ページ更新により全体整合性が失われる ➢ 特にページアーカイブするときは、被リンクページがあれば、それも含めて更新を行う

Slide 45

Slide 45 text

● 気付いたことから繰り返し改善 ○ 英語ドキュメントの構成がバラバラ ➢ ページごと日英分けるパターンと、1ページに日英併記するパターンが混合していたが、後者のパターンでテンプレートを統一 ○ 毎回の修正量・作業時間が減ってきた ➢ 毎週30分実施から、頻度や時間数を減らす運用からのフィードバックループ

Slide 46

Slide 46 text

Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに

Slide 47

Slide 47 text

効果と今後 - 1.5ヶ月のメンテナンスを経て ● ドキュメント数削減！ ○ Before: 199 記事 → After: 158 記事 (21%減) ■ 検索ノイズは確実に減らせている ● 多く改善のきっかけになる ○ 既に非推奨・無効となっていた情報の更新が多くできた ■ 既に移行済みで、推奨していない旧ミドルウェアの資料 ■ SaaS に関する古い契約・Plan 情報 ➢ ドキュメントにここまで書いてあるとは分かっていないまま、メンテが行き届いておらず、ミスリードしているものが多くある

Slide 48

Slide 48 text

効果と今後 - ドキュメント改善プロジェクトを経て ● Platform チームのマインド変化 ○ ドキュメントに関する認識・モチベーションのすり合わせも副次的に大きな効果があった ○ 自分が執筆していないドキュメントでも Platform チームのプロダクトとして、オーナーシップを持ちやすくなる ■ キャッチアップにもなる ○ レビューポリシーによる品質の安定化 ■ 「それぞれの価値観で主観的にレビューする」から「同じ規範・品質水準に基づいて客観的にレビューする」へ

Slide 49

Slide 49 text

効果と今後 - ユーザーインタビュー ● ユーザーインタビューからポジティブな声 ○ ランディングページ辿りやすい ○ 知らないドキュメントの存在に初めて気付いた...！ ■ 今までついググってしまっていたが、社内により具体的な知見があることに気付けた ● 一方で、以下のような意見も ○ 開発者向けポータルのトップページの存在を知らなかった ○ 開発者のオンボーディング資料からの導線も改善できそう

Slide 50

Slide 50 text

効果と今後 - さらに挑戦 ● 機械的な作業の自動化 ○ リンクチェッカー、リンター ○ レビューフローの自動化（Pull Requestスタイルでのレビューなど） ○ メンテナンス契機の通知の自動化 ○ 特定階層配下のドキュメントにラベルを自動付与

Slide 51

Slide 51 text

効果と今後 - さらに挑戦 ● ドキュメントの利用動向を参考に、開発者の利用体験向上を図る ○ ツール提供・開発による開発者の作業負荷軽減 ■ よく利用される How-to ページの自動化ツールの開発と提供 ■ よく利用されるチェックリスト形式ドキュメントのプロセス自動化 ○ さらなる導線改善による開発者の認知負荷軽減 ■ セットで読まれるドキュメントのパッケージング ■ ChatBot などインタフェースの検討 ■ 開発プロセスに応じて、ドキュメントをサジェストする仕組み

Slide 52

Slide 52 text

効果と今後 - さらに挑戦 ● ドキュメントの有効性をどう測る？どう上げていく？ ○ 現在は手がかりとして閲覧数を指標としているが、閲覧数が低いことがだけで有効性を測ることは出来ない ■ 閲覧数 0 には、「見る必要がなかった」「他のドキュメントや情報を見て解決した」「探したが見つからなかった」など様々な要因が含まれるので、原因分析が必要 ➢ 定量的な情報だけで、ユーザーにとっての有効性を測ることは難しい ○ 定性的なデータ収集も増やす ■ アンケート、ユーザーインタビューなどの継続的な実施 ■ Slack で記事 URL を検索して、インサイトを得る

Slide 53

Slide 53 text

Agenda 1. CADDi Platform チームの話 2. Documentation as a Product 3. ドキュメント改善への道 4. 運用実践 5. 効果と今後 6. おわりに

Slide 54

Slide 54 text

おわりに ● ドキュメント運用の仕組み化を明日から始めよう ○ 一過性のものではなく、継続的な活動を ○ 利用しているドキュメントシステムに合わせて、ドキュメントのメトリクスを計測して、きっかけを作ろう ● Platform as a Product. Also, Documentation as a product. ○ 開発者のニーズに合わず価値を提供できないドキュメントはいらない ○ 定量評価だけではユーザーニーズを真に捉えきれない ■ ユーザーインタビューなどを通して、ニーズを集めよう