コネヒトアドベントカレンダー2024 1日目の記事です。
この記事では、コネヒトで4年間運用している行動ログのドキュメント化について紹介します。
行動ログの概要
コネヒトでは、Webサービスやモバイルアプリの開発をしています。その中で、ユーザーがどんな操作をしたのか（例えば、画面を開いたり、ボタンをタップしたり）を「行動ログ」として記録しています。このデータを分析して、サービス改善に役立てています。
しかし、次のような課題がありました。
- 行動ログがどのバージョンから実装されているのか分からない。
- イベントがどのタイミングで発火するのか明確でない。
- 情報がまとまっていないため、ソースコードを確認しなければならない。
これらの課題を解決するために、2020年に行動ログのドキュメント整備を始めました。
ドキュメント作成の取り組み
選んだアプローチ
ドキュメントは、理想的にはコードから自動生成される形が望ましいですが、実装を大幅に変更する必要があり、工数が膨大になると判断しました。そこで、ライトに始めることを優先し、以下のような形式でMarkdownを用いて人の手で記述することにしました。
フォーマット例
コードをコピーする # 行動ログのフォーマット # EventName <!-- イベント名 --> ## Description <!-- イベントの説明文 --> ## Trigger <!-- イベントが発火する条件 --> ## Parameter |key|type|requirement|description|available version| |:--|:--|:--|:--|:--| |a|b|c|d|e| ## Send to - [ ] Mixpanel - [ ] Firebase ## Version ### Available Version - iOS - vx.x.x~ - Android - vx.x.x~ - Web - 202x/xx/xx 以降 ### Unavailable Version <!-- 不具合などで動いていない時期があれば記載する -->
このフォーマットは2020年に作ってからほとんど変わっていませんが、今もこれで十分便利に使えています。
運用ルール
ドキュメントの運用は以下のように行っています。
- Markdownで記述したドキュメントをGitHubで管理。
- 実装前にドキュメントを作成し、GitHub上でレビューを受けるルールを導入。
- 実装変更時にドキュメントの更新漏れを防ぐため、アプリケーション実装時のPRレビュー時のテンプレートに「行動ログの仕様を記載したか」というチェックボックスを追加。
社内への浸透施策
行動ログはエンジニアだけでなく、分析を行う他職種のメンバーも利用します。そのため、GitHubに不慣れな人でも使いやすい形にする必要がありました。そこで、Markdown形式のドキュメントをNext.jsを使ってWebページ化し、社内で閲覧できるようにしました。
また、ドキュメントの認知を広めるために以下の施策を行いました。
- 行動ログについて質問された際に「こちらを参照してください」とリンクを送る。
- Slackに行動ログWebページのリンクを簡単に表示できるショートカットを作成。
- 行動ログの分析ワークショップを開催し、ドキュメントの活用方法を布教。
これらの取り組みを続けた結果、現在ではほとんどのメンバーがこのドキュメントを認知して活用してくれていると思います。
4年運用してみて
運用を始めてから4年が経過しましたが、行動ログのドキュメントは引き続きメンテナンスされ、サービス改善に活用されています。
課題と振り返り
一方で、次のような課題も明らかになりました。
Next.jsでWebページ化したものの、メンテナンスする人はごく一部だけでした。「社内ツールは実装した人しか触らない」というあるある問題ですね。 今なら、最初からNotionなどの既存ツールを使うのも良い選択肢かもしれません。
まとめ
ドキュメントは「作って終わり」ではなく、使われ続け、適切にメンテナンスされることが大事です。そのためには、会社の規模や文化に合った方法を選ぶことが重要だと思います。
コネヒトの事例が、みなさんのヒントになれば嬉しいです！
