Platform Engineering Kaigi 2024 で「開発者向けドキュメントの改善」をテーマに登壇してきました

こんにちは、Platform チームの @akitok_ です。
CADDi Platform チームでは、チームトポロジーの定義に基づいてストリームアラインドチームが自律的に仕事を届けられるようにするため、様々なアセットとそれに付随するドキュメントなどを提供しています。 Platform チームのミッションやその活動などについては、以下の記事などを読んでいただけますと幸いです。

今回、Platform Engineering Kaigi 2024 というイベントで、この Platform チームを取り巻く開発者向けドキュメント改善について登壇してきました。この記事では、イベントの雰囲気や当日資料の補足、また当日 sli.do でいただいた質問への回答などを書いていきます。

Platform Engineering Kaigi 2024
登壇セッション
感想
sli.do でいただいた質問への回答
終わりに

Platform Engineering Kaigi 2024

Platform Engineering Kaigi は、現在注目を浴びている Platform Engineering をテーマにした日本初のテクノロジーカンファレンスです。その初回である今回は、docomo R&D OPEN LAB ODAIBA で開催されました。

www.cnia.io

#PEK2024 現地企画紹介：フォトパネル

Platform Engineering Kaigiのフォトパネルを入口横に設置しております！
カンファレンス参加の記念に一枚いかがでしょうか！ 📷✨https://t.co/4KK23vEQk9 pic.twitter.com/6dQhUSKNwS
— Platform Engineering Kaigi / クラウドネイティブイノベーターズ協会 (@cnia_pfem) 2024年7月8日

最終的な参加者登録者数は996名だったそうで、実際に会場は非常に活気があり、注目度の高さを感じました。

登壇セッション

当日は13:45 - 14:15 に Track A で登壇させていただきました。

www.cnia.io

アーカイブはこちらから見ることができます。

www.youtube.com

資料はこちらです。

speakerdeck.com

感想

ここからは登壇者としての感想です。
私個人としてオフラインかつ大規模イベントでの登壇はなかなか久しぶりだったため、内心かなり緊張していました。ですが、運営の方はもちろん、イベント全体としてどことなくアットホームで、開発者フレンドリーな雰囲気が作られていて、非常に落ち着いて発表させていただくことが出来ました。主催者・運営の方はもちろん、イベントに関わったすべての皆さんに感謝です。

また、登壇直後に質問や感想を伝えに声をかけていただいたり、懇親会でドキュメントや Platform Engineering について、それぞれ異なる会社に所属し、異なる背景を持つ中で、意見交換出来たことは本当に有意義でした。社内で言えば Platform チームは現在4名しかおりませんが、視野を広げると国内にこんなに仲間がいるんだと思えました。ありがとうございます。

sli.do でいただいた質問への回答

ここからは、sli.do でいただいた質問に回答します。

ドキュメントを捨てるのが難しい気がしています。捨てる基準など設けてGarbage Collectしていますか？

ドキュメントの廃棄、勇気がいりますよね。

私たちのチームでは、現在は Confluence のアーカイブ機能を用いて廃棄しています。
Confluence では記事のアーカイブをすると、デフォルトでは検索にヒットしなくなり、ドキュメントのサイドバーツリーにも表示されなくなりますが、URL は残ります。
このアーカイブ機能を使って、認知負荷を下げつつ、情報自体は保持するようにしています。

捨てる基準について、シンプルなルールなどは今はありません。
登壇でも説明したように、鮮度や有効性の低下傾向をトリガーに Platform チームで判断し、主に以下のようなドキュメントをアーカイブしました。

明らかに、既に非推奨・無効になっているもの
同じ目的のドキュメントが新しく誕生していて、過去に廃棄すべきタイミングで廃棄し損ねていたもの

各ドキュメントにバイネームでメンテナーを設定しているのでしょうか？

資料ではメンテナーという言葉を使いましたが、Confluence の機能でいえばオーナーです。ドキュメントを最初に作成した人が自動でオーナーになります。
Confluence ではオーナーを変更する機能があるので、鮮度チェックによるメンテナンスの中で、既にオーナーが不在であればオーナーを現在の Platform チームメンバーに変更しています。
ドキュメントシステムごとにドキュメントのオーナーや最終更新者など様々なメタデータがあると思いますので、お使いのドキュメントシステムに合わせて読み替えて頂ければと思います。

レビューポリシーについて、例えばどのようなものを設定していますか？

入社いただければ閲覧できます！
というのは冗談で、今回説明時間の都合で細かく読み上げなかったのですが、資料の27スライド右側に機能品質のレビューポリシーを一部抜粋したものを表示しています。
レビューポリシーの構成としては以下のようになっています。

機能品質に対するチェックリスト
構造品質に対するチェックリスト
ドキュメントタイプごとのチェックリスト

機能品質・構造品質のチェック内容としては、資料でも紹介した「ユーザーの問題解決とプロダクトの成功を導くエンジニアのためのドキュメントライティング」の Chapter 9 の内容を参考にしています。
ドキュメントタイプごとのチェック内容としては、Documentation topic types (CTRT) | GitLab を参考にしています。

ドキュメントの新規作成・レビュー・メンテナンスの各フェーズの方針には触れられていましたが、Platfrom Enginneringを効果的に提供するために「どのようなドキュメントが足りていないか」をシステマチックに検討し続ける仕組みも何か検討をされていたら共有頂けるとありがたいです。

ドキュメントが網羅的にカバー出来ているかどうか、非常に重要な観点だと考えています。
ただ、現時点で具体的なアプローチは出来ていないのが現状です。
私たちのプロダクトは急成長しながら変化も非常に多いフェーズにあります。
過剰な網羅性を求めすぎると、開発者にとっては認知負荷を増やすことにも繋がりますので、網羅性についてどこまで投資するかは悩みながら進めています。

ドキュメンテーションは重要ではありますが、活動を始めてから人を拡大していくのが難しいと考えてます。どのようにして、この活動を継続して続けてくれる人を探してますか？

今回は、Platform チームが開発者に提供するドキュメントをスコープにお話させていただきました。そのため今回のスコープに関して言えば、Platform チームメンバーの業務の中で継続的に活動しています。

実際に週３０分のドキュメント改修がプロダクトのアジリティ向上にどれだけ寄与できているか計測していたりしますか？

ドキュメント改善による得られる効果の計測・定量化は、現在は出来ておりません。
開発者の閲覧行動の変化（閲覧数の増減など）はアジリティ向上とはイコールではありませんし、four Keys や SPACE などいわゆる開発生産性を示す指標もドキュメント改善と結びつけて判断するのは非常に困難で、過剰な数値化によりミスリードが生まれる可能性もあると考えています。
そのため、まずは開発者とのインタビュー、アンケートなど定性的な評価を集めて、フィードバックを繰り返しいきたいと考えています。
また、週30分の活動量捻出に対する費用対効果という観点で言えば、最初はドキュメント量が多いので時間がかかってしまいますが、改善が進むにつれ毎回の作業量が減っていきますので、実施頻度や時間数を減らすことで作業コストは減らしていけると考えています。

この手のものの次にChatGPT + RAG とかもあるかなと思っているのですが、そういったものも検討されたりしていますか？（うちでも膨大な社内ドキュメントをRAGで、、みたいな話があり）

具体的に検討までは至っていないですが、開発者が情報を取り出す際に ChatBot のようなインタフェースで必要な情報を提供出来る仕組みは、チーム内のアイデアとしては話題に上がっています。

Confluence のドキュメント品質を計るための各数値はどのように取得していますか？

これは Confluence API をコールして、TSV を出力するツールを実装して、対応しています。具体的には、大きく以下3点実施しています。

開発者向けドキュメントすべてに同じラベルを付与する
私たちのチームではドキュメントのポータルページを親として、その配下にツリー構造ですべての開発者向けドキュメントが配置されています。
この構造を利用し、以下の API で、ポータルページの配下に位置するページの content id を再帰的にすべて取得します。
https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-children/#api-group-children
その content id リストを基に、以下の API を用いて、取得した content すべてに特定のラベルを付与しています。
https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content-labels/#api-wiki-rest-api-content-id-label-post
鮮度低下が見られるドキュメントをリストアップする
以下の API を利用して、CQL で最終更新日が6ヶ月以上前で、かつ特定のラベルがついているものという条件で、ドキュメント一覧を取り出しています。 https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-search/#api-wiki-rest-api-search-get
有効性低下が示唆されるドキュメントをリストアップする
これは以下の 2 step で実施しています。
(1) 特定のラベルがついているドキュメントを以下の API を用いて、すべて取り出して、content id のリストを作る
https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-page/#api-labels-id-pages-get
(2) 以下の API に対して、contend id のリストを基に、1件1件リクエストして、Page view を取得する
https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-analytics/#api-wiki-rest-api-analytics-content-contentid-views-get

終わりに

今回、Platform Engineering にまつわるドキュメントをテーマに取り扱いました。登壇の中で話した機能品質に立ち返って言えば、想定読者とゴールは以下のようなものでした。

想定読者
- Platform Engineering を実践している、あるいはこれから実践しようと検討している人
ゴール
- 想定読者が、職場に戻ってからドキュメントの重要性を再確認し、チームで意見交換し、継続的なドキュメント改善を行う仕組み作り、きっかけ作りを始められること

このような機能品質を達成するために、資料や説明上は Platform Engineering を切り口にしていますが、ドキュメント自体はどこにも溢れていて、他の分野でも社内外の情報流通を助ける非常に重要なパスで、ある程度普遍性のあるテーマでもあったとも考えています。
社内でもシェアしてくださる方もいて、データマネジメントチームやコーポレートチームからもポジティブな反応がありました。嬉しいですね。