カケハシのプラットフォームチームでソフトウェアエンジニアをしているすてにゃん (
id:stefafafan) です。今回はチームに配属されて数ヶ月の私が、いかにして社内ドキュメンテーションの階層構造を整理し、情報の検索性を向上させたかについてお話します。
はじめに
カケハシでは全社的にドキュメンテーションツールとして esa - 自律的なチームのための情報共有サービス を利用しています。それぞれのチームやプロダクトごとに階層を切ってドキュメントを書いています。
プラットフォームチームでは認証基盤などの社内プラットフォームシステムを開発しているため、自チームが運用する各種のリソースが社内のさまざまなチームから参照される立場にあります。そのため、ドキュメントについても自チーム向けにとどまらず、社内の他チームが参照しやすい形にすることがとても重要になります。
そういった背景もあり、過去にもプラットフォームチームのテックリードよりドキュメンテーションに関する記事が投稿されました。
上記の記事は考え方としてとても共感できたのですが、配属されて間もない自分としてはチームのドキュメンテーションに課題を感じました。そこで具体的に何を課題だと考えているのかを言語化し、改善に向けて取り組んできました。
この記事の想定読者
この記事は、社内ドキュメンテーションの整理の仕方について悩んでいる方を対象としています。特に esa のような階層型のドキュメンテーションツールを利用している（もしくは検討している）人にとって参考になると思います。
課題意識
入社して間もなかった私は、オンボーディング資料で共有されたいくつかのページを元にどうにかこうにか知りたい情報に辿り着いていました。どこにあるかわからない場合は esa や社内チャットツールである Slack を検索して見つけるか、チームメンバーに都度聞いていました。社歴の浅さの影響もあるとは思いましたが、それにしても「情報の見つけやすさが足りない！」と直感的に感じました。
以下のような点に課題を持っていることがわかってきました。
- ① 記事を探す際の認知負荷が高い
- 第 1・第 2 階層 (esa ではカテゴリという名前がついています) の時点で横並びにカテゴリが多く存在するため、どのカテゴリに入っているのかを探すのが大変
- 例えばとある仕様について調べたい時に、
開発という階層と運用という階層があった際にどちらに知りたい情報があるのかが自明ではない
- 例えばとある仕様について調べたい時に、
- カテゴリごとの用途や使い分けが自明ではない
- カテゴリの階層が深くなりがちなため、サイドバーから辿っていくには何度もクリックすることが強いられる
- 記事を検索しようにもどういうキーワードで調べれば良いかがわからない
- 第 1・第 2 階層 (esa ではカテゴリという名前がついています) の時点で横並びにカテゴリが多く存在するため、どのカテゴリに入っているのかを探すのが大変
- ② 記事を執筆する際の認知負荷が高い
- どのカテゴリに記事を置くかを判断してから記事を書かねばならないため、① の課題が ② にも響く
課題を言語化することができたので早速手を入れたいところではありましたが、その前に準備としていくつかのことを実施しました。
メンバーへの共有と相談
「チームの仕事のやりかたを大幅に変更したいです」と入社して間もない私がいきなり提案するのは既存社員にとってはもしかしたらとても大きなストレスになるかもしれません。そう思った私は、チームのテックリードとの 1on1 で上記の課題感について提案することにしました。どれくらいの温度感でこういった提案が受け入れてもらえるのか、どれほどの丁寧さで提案資料をまとめるべきかのすり合わせができてとてもよかったです。
何よりも、テックリードも少なからず課題感を持っていたようだったため、自信を持って改善に取り組めるようになりました。
社外事例の調査
改善を行うにあたり、自分の頭でゼロから考えるのではなく社内外の事例を集めて参考になる良い取り組みがあればそれを取り入れようと考えました。特に esa についての知見を自分は持ち合わせていなかったので、公式ドキュメントや esa を利用している他社のブログ記事を調べました。社外事例として特に参考になったのは以下の 2 つの記事です。
esa の階層整理
今回私は以下の方針で改善を進めることにしました。
- 自チームの現在触っている範囲にフォーカスして限定的に対応する
- ほぼ触れられていないプロダクトのドキュメントについて今大きく変えることによって短期的に得られるメリットが少ない
- 部門や会社レベルで変更を適用するには調整コストによって改善そのものがストップしてしまう懸念があると考えたため、まずはチームレベルで運用を変更してみて効果を確認する
- 階層整理の思想として
- カテゴリの数を必要になるまでは無闇に増やさず、それぞれの役割を明確にする
- 繰り返し参照されるようなストック情報はアクセスしやすい浅い階層になるべく置く。一回限りのフロー情報はアクセスしたくなる頻度が少ないため深い階層になっても問題ない
第 1・第 2 階層の整理
弊社では第 1 階層に プロダクト と チーム というカテゴリがあります。使われ方としては名前の通り、特定プロダクトのドキュメントをプロダクト配下に置き、チームに関する話題はチーム配下に置きます。
- プロダクト - プロダクトA - プロダクトB - チーム - チーム1 - チーム2
私の所属するプラットフォームチーム（厳密にはそのサブチーム）では現在 2 つのプロダクトの開発・運用をしています。プラットフォームとして他チーム向けに展開したいドキュメントもあるため 他チーム向け というカテゴリをわけることで情報の整理を行っていました。
- プロダクト
- プロダクトA
- 他チーム向け
- 開発
- 運用
- ...
- プロダクトB
- 他チーム向け
- ...
- チーム
- プラットフォームチーム
この構成は理解できますが、実際に日々ドキュメントやちょっとした記事を書きたくなった時に プロダクト と チーム カテゴリのどちらに書くべきなのかということを意識しないといけないうえに、他チームが参照したくなった際も プロダクト/プロダクトA/他チーム向け/ 以下を見にいく必要がありました。 プロダクト/プロダクトA/他チーム向け/ に向かう過程で他の 開発 や 運用 などの関係ないカテゴリも目に入るため、少なからず情報を見つける時にノイズになっていたと思います。
これらのカテゴリの意味合いを見直して、以下のように整理しなおすことをチームに提案しました。
プロダクト: 他チーム向けの内容を配置する公開用ドキュメント置き場チーム: 自チーム向けに何でも置く場所
具体的には以下のように変更してみることにしました。
- プロダクト
- プロダクトA
- (他チーム向けのドキュメントのみ置かれている)
- チーム
- プラットフォームチーム
- プロダクトA
- 開発
- 運用
- ...
- (プロダクトに紐づかないチームに関するさまざまな記事)
些細な変更ですが、この変更によりチーム内外の認知負荷の軽減に貢献できたと思います。
- チーム外:
プロダクト/プロダクトA/以下さえみれば、チームに所属していないメンバーでもそのプロダクトのことがわかりやすくまとまっていて嬉しい- チームメンバーにとっても、配属直後にプロダクト A について気になった際にここをみれば良いという状態になる
- チーム内: 日々思ったことや開発中のメモは全て
チーム/プラットフォームチーム/配下のみ考えれば良いため、ドキュメントを探す際も書く際も若干わかりやすくなった
プロダクト A の情報が チーム 配下にも露出するこの変更はイマイチなのではないかという指摘もあると思います。ただ、ドキュメントを完全にチームから独立させることは、複数プロダクトを管理する際チームメンバーにとっての認知負荷は高いと思うので、今回はこの整理を選択しました1。esa の記事は URL が固定で、カテゴリの移動はとても気軽に行えるのでそういう点でも安心して実行できました。
ストック情報とフロー情報を意識した階層の整理
esa はストックしたい情報と、リアルタイム性のあるフロー情報を両方扱えるサービスとして意識して作られています。
チャットなどのリアルタイム性の高いフローなツールは、発信への敷居を下げることには成功しましたが、一方で有用な知見を網羅的に管理するようなストック方面はあまり得意ではありませんでした。 一方、Wikiは情報を整理するストック性は優れていますが、発信への敷居はやや高いものです。
esaはこのフローメディアとストックメディアの両者の特性をかけ合わせ、チャットのようなリアルタイム性や発信の敷居の低さと、Wikiのような情報整理との両立を目指しました。
コンセプト - esa
ドキュメントの階層を考える際にも同様にストックとフローを意識した整理をしました。元々 チーム カテゴリ配下は以下のような構成になっていました。
- プラットフォームチーム
- 日報
- 2024
- 07
- プロダクトA
- ログ
- 調査
- 2024
- 07
- 議事録
- 2024
- 07
- 意思決定
- ログ
- 議事録
- 2024
- 07
- 運用
- チーム運営に関する手順など
- 意思決定
- チーム運営に関する意思決定など
この中の情報をストックとフローで分類した時に、以下のような整理になります。
- ストック
- プロダクト A に関する意思決定 (
プラットフォームチーム/プロダクトA/意思決定) - チーム運営に関する手順 (
プラットフォームチーム/運営) - チーム運営に関する意思決定 (
プラットフォームチーム/意思決定)
- プロダクト A に関する意思決定 (
- フロー
- 日報 (
プラットフォームチーム/日報) - プロダクト A に関するログ (
プラットフォームチーム/プロダクトA/ログ) - プロダクトに閉じない、チーム会議の議事録 (
プラットフォームチーム/ログ)
- 日報 (
ストック情報とフロー情報が入り混じっており、かつ 日報 のようなカテゴリがものすごくアクセスしやすい一等地のような場所に位置しています。本来頻繁に辿り着きたいことが多いであろうストック情報を見つけるには目でフロー情報を飛ばして階層を開いていって探す必要があります。
そこで以下のような整理を行いました。
- プラットフォームチーム
- 1. 暮らし
- 例: 開発ガイドライン
- 例: デイリースクラム #スクラム
- 2. プロダクトA
- 1. 運用
- 例: リリース手順 #手順
- 2. 意思決定
- 例: XXで使うライブラリについてはYYを利用する #ADR
- 3. ドメイン
- 例: 他社事例集
- 2024
- 07
- 例: 2024-07-10 CI/CDで発生したエラーに関する調査 #調査
- 例: 2024-07-09 先方との打ち合わせ #議事録
- 2024
- 07
- 例: 2024-07-10 stefafafan #日報
- 例: 2024-07-10 チームの未来について雑多に話す会 #議事録
上記で実施した工夫はいくつかあります。具体的には
- フロー情報は
議事録や調査のようなカテゴリ内に入れずに、直接2024/07のような日付のカテゴリに入れる - よく目にしたい内容については
1.のような数字プレフィックスを振ることにより esa 上のカテゴリの並びを制御する - これまで置き場所に困っていた記事を置くカテゴリを新設 (
暮らしとドメイン) - 検索機能経由で辿って絞り込む補助として、
#ADRや#議事録といったタグを活用する
このように整理したことによって、プラットフォームチームのドキュメントや記事を esa のサイドバーから探し出す時にフロー情報がノイズにならずに簡単に目当ての機能に辿り着けるようになりました。カテゴリの順番を制御したことにより、記事数の多さによって順番が動的に変わる（以前は日報を毎日書いていたことで 日報 カテゴリが必要以上に上の方に位置していた）ことを避けることができて、認知負荷を軽減させることもできました。
esa の機能をフル活用する
今回ドキュメンテーションの整理をする中で esa 特有の機能の活用もいくつかしてきたので、ここで紹介します。
まず、既に紹介したカテゴリに数字を入れることによって並びを固定できる機能です。こちら去年末に追加された機能で、これがないと「記事数の多い順」でしか並ばないのでとても便利に活用しています2。
次に、README の設定です。カテゴリごとに README という記事を置いておくとそのカテゴリを開いた際に README の内容がファーストビューに入って便利です。私はここにそのカテゴリの用途や、よくある質問、新しい記事を投稿したい時に使える投稿テンプレートの URL を貼ったりします。
そして投稿テンプレート。特にフォーマットの決まった記事を繰り返し書く際になるべくこれを用意して使える状態にしています。特定のカテゴリ内にある場合は自動で適用されるのが便利です（ただし、今回フロー情報を 日報/2024/07/ みたいにカテゴリに入れずに直接 2024/07/ 以下に入れるようにしたので、テンプレートの自動適用が使えない形にしてしまった部分もあるので、そういう場面では README のわかりやすい場所にテンプレートへの URL を貼るようにしています）。
効果や今後について
今回カテゴリを整理したことによって、何か数値としてわかりやすい効果は示すことは難しいですが、少なくとも実施した個人の感覚としてはとても情報の見つけやすさと記事を書く際の迷わなさは上がった感じはします。また、そもそもこの活動を私がする中でドキュメンテーションについてチームで話す、考えるきっかけにはなったと思うので、それだけでも実施した意味はあったのではないかと思います。
今後チームのドキュメンテーションをさらに大幅に変更する予定があるわけではありませんが、私に限らず他メンバーがやっぱりここをこう変えたいと思った時に都度チームで会話しながらベストな整理を模索していきたいと思っています。欲を言えば自分のチームに閉じずに、社内の他部署にも影響を与えたいというのもあります。今回こうしてテックブログに記事を書くことは社外へのアウトプットという意味合いもありますが、社内のいろんな人に私たちがチームでやったことを展開するという裏の意図も実はあったりします。
日々のコミュニケーションやドキュメンテーションはこういった小さな改善によってどんどん良くしていけるので、この記事を読んだみなさんにも何かしら良い影響を与えることができたら幸いです。
