🎄 本記事は ZOZO Advent Calendar 2024 シリーズ 2 の 3 日目です。
推薦基盤ブロックの2日目の記事はｺｳｽｹｽﾐﾔｽさんによる推薦システムにおける新規性に関して、考えてみませんか？でした

はじめに

こんにちは。データシステム部推薦基盤チームの関口です。最近、筋トレ（ベンチプレス）に励んでおり、6ヶ月で最大重量を80kgから107.5kgに増強しました！コツは、筋肉痛があってもとにかく継続すること。量をこなすことが重要だと実感しています。来年夏には120kgを目指します！

さて、本題です。システム運用におけるドキュメントの重要性についてお話します。設計、実装、運用、トラブル対応…あらゆる場面で欠かせない存在にも関わらず、ドキュメント整備は後回しになりがちです。これにより、

システムに関する知識が属人化し、特定のメンバーがいないと対応できない
トラブル時に迅速な原因特定ができない
新メンバーがスムーズにプロジェクトに参加できない

といった問題が発生します。そこで私たちのチームが実践しているドキュメントの管理方法についてまとめようと思います。

システムの運用ドキュメントの目的

MLパイプラインやAPIなど、多数のシステムを管理する私たちのチームでは、以下の目的でシステムごとの運用ドキュメントを作成・維持しています。

属人化の防止
新規メンバーの円滑なオンボーディング
トラブル対応の迅速化
システム変更の影響把握

ドキュメント整備の基本方針

ドキュメントの基本構成は以下の通りです。（システムごとに必要な追加要素はあります。）

├── README/
│   ├── リポジトリの目的
│   ├── 動作確認方法
│   ├── リリースフロー
│   └── 関係者リスト
├── システム構成/
│   ├── アーキテクチャの概要図
│   ├── 関連システムとの関係性
│   ├── 処理フロー
│   ├── ML アーキテクチャ
│   ├── 使用しているサービスについて（GCP等）
│   └── etc...
├── 設計資料/
│   └── 開発時の設計資料
└── 運用資料/
    ├── 運用に関する議事録
    ├── 運用履歴
    └── 改修案件資料

ここで重要なのが、システム構成では必要最低限の情報だけを載せることを意識しています。なぜ必要最低限にするかは以下が理由です。

システムの詳細はコードを読めば確認できる
ドキュメントに詳細な部分まで書くと、細かなシステム改修時にもドキュメントも修正しなければいけなくなる
上記を徹底しないとコードとドキュメントに乖離が発生する

なるべくメンテナンスコストをなくすことを意識してドキュメントの作成を行っています。

ドキュメントの運用で失敗しないための取り組み

定期的なドキュメント整備

私たちのチームでは保持しているすべてのシステムのドキュメントを作成するために週2回1時間の大ドキュメント書き大会を実施していました。この会ではチーム全員で集まり、担当の運用ドキュメントを整備する時間として確保しています。ドキュメント整備を行う時間を確保しておくことで、他の業務への集中度を高めることができます。
ドキュメントが完成した後は、改めてドキュメント更新の担当者を設けて確認する時間として確保しています。

システム共有会の実施

整備したドキュメントをもとにシステムの共有をチーム内でシステム共有会を開催しました。これによりシステムの属人化を防ぐことを目的としています。また、新規メンバーに対するオンボーディング資料としても活用できます。

まとめ

効率的なシステム運用には、質の高いドキュメントと、それを維持するための仕組みが不可欠です。私たちのチームでは、必要最低限の情報に絞ったドキュメントと、定期的な整備、共有会という仕組みによって、属人化を防ぎ、スムーズな運用を目指しています。筋トレと同様に、継続的な努力が重要です。ﾊﾟﾜｰーーーーーーーーｯｯ!!!!