はじめに
この記事はMIXI DEVELOPERS Advent Calendar 2023の 21 日目の記事です。
モンスト解析グループ(以降解析グループと表記) の kimuson です。
今回は私が所属している解析グループで行った GitHub Discussions を利用した開発プロセスの改善についてまとめました。
モンスト解析グループについて
まず軽く解析グループについてです。
解析グループはモンストにおけるデータの分析・可視化とデータ基盤の開発と運用を主に行っている部署になります。
解析グループには分析業務を主に行う分析チームと、データ基盤の開発業務を主に行う解析チームの 2 つが属しています。
より詳しくは、解析マネージャー吉野による MIXI TECH CONFERENCE での登壇時の資料をご確認ください。
今回この記事でまとめた開発プロセス改善は、開発に焦点を当てたものにはなっていますが、改善時の問題点の洗い出しから導入に関する議論には解析グループ全体で取り組みました。
どういうプロセスだったのか
解析グループでは基本的に GitHub の issue ベースで開発をしています。
なにか解決したい課題があったときに issue が作成され、それに関しての調査のログや相談したいこと、メモなどを issue に残していくようにしていました。
そして、その issue を元に 変更や実装が必要なら PR が作成され、メンバーにレビューをしてもらい、承認されたらマージとデプロイが行われるようなプロセスになっていました。
解析グループでは issue comment が Slack のチャンネルに流れるようになっているため、それを見たメンバーが代替案や懸念点をコメントしてくれることもあります。
リモートで業務を行っているメンバーもいるので、情報の集約点としてなるべく全てを Slack から確認できるようにしていました。
また、このように issue に固めることで後から確認する際に issue を見るだけで大体の流れがわかるようにしていました。
しかし、GitHub の issue を主に使っていたため、以下のような問題がありました。
- 特定の issue comment に返信するのが難しい
- なるべく全てを issue comment に書くようにしているので流れやすい
特定の issue comment に返信するのが難しい
GitHub issue には、Slack でいうところのスレッド機能に対応していません。
そのため特定のコメントに対して何か返信したい場合、うまくそのコメントに対して返信していることを表現するのが難しかったです。
> hogeのように引用して返信したり、返信したいコメントのリンクをコメントのトップに貼るなどの工夫をしていました。
1 回くらいコメントに返信する分には引用でもなんとかなりますが、複数のコメントに返信したかったり、返信が何度か続く場合や、複数のメンバーが別々の観点に対して返信をする場合はだんだん誰が何に対してコメントをしているのかよくわからなくなってしまいます。
コメントのリンクを貼る方針だと、そのリンクを開くとリンクのコメントの位置まで遷移するため、対象のコメントとそれに対する返信を同時に確認することが難しかったです。
なるべく全てを issue comment に書くようにしているので流れやすい
issue に議論から、進捗やメモ書きなどのなるべく全てを残そうとしているため、必然的にコメント量がとても多くなります。
何もコメントが書かれないよりは多くコメントがある方がいいですが、実は議論した方が良かったこともどんどん流れていました。
issue のコメント量が多くなると、一部は折りたたまれてしまうのでその折りたたまれている中に要点がある場合に気付けないこともあります。
影響
これによって、本来は issue の課題解決の方針を考える段階や、設計をしている段階で気づけた可能性があった問題・懸念点がある程度実装をして PR を作成していざレビューをしてもらう段階になってようやくその点に気づけることが何度かありました。
メンバー全員が常に自分以外のメンバーの issue の動きを漏れなくチェックしながら自分の受け持っているタスクもこなしていくというのは現実的ではないです。
これに加えて、GitHub の issue にすべてなるべく書いていくようにするというのは変更したくなかったので、仕組みでどうにかできないかと考えました。
どうしたのか
結論としては議論をしたかったり、設計の段階でレビューや相談をしたい場合は GitHub Discussion を使用するようにしました。
それを決定するまでにどのようなことを行なったか、どのような議論を行ったかについて詳しく書いていきます。
意義の説明
まず最初に設計の段階でチームに共有し、それをレビューしてもらうことがしたかったため、Design Docs をチームにあった形で導入すればいいのではとなりました。
しかし、ただ Design Docs をそのまま導入して、これからはこの通りに書いてもらうというようにすると、何のためにやっているのかわからないめんどくさい工程になってしまいそうでした。
そもそもタスクの中にも工数のかかるものと、すぐにできるものがあるため、全部のタスクで書く必要があるのかという問題もありました。
そのため、なぜ Design Docs を書いた方がいいのか、どのようなタスクを受け持ったときに Design Docs を書くのが有効なのかを４ページほどのドキュメントにしてまとめて共有しました。
ドキュメントの内容は以下に議論に大きく関わってきたとこのみ抜粋しています。
抜粋したドキュメント内では示されていないですが、当初は Google Docs に書いていくようにするつもりでした。
## 目的
DesignDocsを書く主な目的は、以下の2つになります。
- これを持って他のメンバーなどの関係者との共有、議論を行うことによって事前に全体を考察し、精度を高め開発後の手戻りを減らすこと
- レビュー時にお互いの認識が取れているので、レビューしやすくマージまでの速度を早めること
## 期待していること
期待していることは以下です。
- 進捗のアウトプットと設計を切り分けること
- 議論したい場所を明確にすること
- 設計を早めに共有して、共通認識をとること
- このプロセスを繰り返して、より解析チームにあった形にすること
これまでのissueベースは、問題点や解決したいことを管理するのには適しています。
しかし、進捗のアウトプットと設計が入り乱れることによって、設計が流れてしまうことや、相談したいのかどうかわかりにくいことがありました。
## 期待していないこと
期待していないことは、設計の細部の細部まで詰め込むことと、最新のドキュメントとしての状態を保たせることです。
設計の細部の細部まで詰め込むと、DesignDocsを読む方も書く方も辛いし、そこまでいったらコードで表現して欲しいとなってしまいます。
いくら設計をしても、やってみたら若干実装方針が変わることもあると思います。その度にやっているとキリがないし、修正の時間が取られすぎてしまいます。
1つ言えるのは、大きく方針を変えないといけない = 元の設計がよくなかったことになります。
どのようにしていくかの議論
ドキュメントを共有したところ多くの意見を開発を担当している解析チームだけでなく、解析グループのメンバー全体からいただき、そこから議論を行いました。
ここでは特に目立った意見を主に紹介していきます。これらについて回答や議論をしていった結果、より良さそうな方向が見えました。
- 期待することの方がやりたいことに直結しているように見えていて、目的が実は違うのではないか
- Google Docs で書くようにすると、ドキュメントが分散してしまい検索性が下がってしまうのではないか
- 現状の運用で issue に書かれていることのほとんどを Design Docs に移行することになりそうだが、そうなると issue には何が書かれるのか
目的が違うのではないか
これについては再度考えてみたところ、一番の目的がPR のレビューの段階になってそもそも方向性が思っていたのと違っていた場合、手戻りが多くなってしまうので先に共有してすり合わせしておくことでそれを防ぎ、マージまでの速度を早くすること だということが自分の中ではっきりしました。
検索性の低下をどのように防ぐか
既存のプロセスの部分でも少し触れましたが、基本的には issue に全部書くようにしており、それを Slack にも表示するようにしています。検索したくなった時は Slack から検索すると issue のコメントも拾えるので見つけやすくなっているため、それを Google Docs に散らすと検索性が下がるのではという意見です。
この意見を受けて、Google Docs での運用は既存の開発プロセスとの乖離が激しいため、難しそうだなと判断しました。
実際私自身も何かわからないことがあったときにまず Slack で似たような事例が過去になかったかを調べることを頻繁に行なっているので、検索性は導入する上で非常に大事な観点でした。
issue には何が今後は書かれるのか
Design Docs 導入後の issue には日々の進捗やメモ、何か思ったことを書くような場になることを想定しました。
現状は設計や方針などの本来ストック情報と、日々の進捗やメモなどのフロー情報として流れていくようなものが issue という 1 つの場に混在しているのを切り分けたかったためです。
議論を踏まえて
これらのような議論をしていく中で、初めから Design Docs のような形式を定義して書いてもらうようにするよりも、何かより手軽に始められて issue のようなざっくばらんに書く場所 と設計や相談する場所を切り分けていくことの良さを感じられるようにするのがいいのではと考えました。
そして、何度も GitHub Discussions の利用を繰り返していって形式が見えてきたらその形式をテンプレートとして用意するのが良さそうということになりました。
GitHub Discussions の導入
issue と分けた議論を実際に行う場所としては GitHub Discussions を使うことにしました。
GitHub Discussions を選定した理由は、先ほどの議論の部分にもあった通り Google Docs の場合、ドキュメントが分散され検索性が低下してしまうのがネックとなるのに対して、GitHub Discussions なら GitHub で完結するからです。
さらに、GitHub Discussions ではコメントに対してスレッドで返信をすることができます。これによって、issue を利用していた際のコメントに対する返信の難しさを解消することができました。
ただ、GitHub Discussions には導入時の段階では Slack integration でコメントを Slack に通知することができないという問題がありました。
解析グループにはもともと、GitHub の Webhook からイベントを受け取る仕組みと、GCP の Cloud Pub/Sub 経由で Slack API を利用して Slack に通知を行う仕組みが整っていたのでそれを組み合わせるだけでよく、非常にお手軽に実装することができました。
通知の仕組みが整ったところで、実際に何か相談したいことや、比較的規模が大きかったり影響範囲が広いものを実装する際には GitHub Discussions に議論や相談したい部分を実装に着手する前に立ててそれを他のメンバーに共有して議論をしていくといった運用を始めました。
その後どうなったのか
GitHub Discussions を導入した結果、issue の段階で相談したいことがある場合やただ単に壁打ちをしたい場合に活発に GitHub Discussions を利用して議論するようになりました。
当初導入しようとしていた Design Docs ほどかっちりしていないため、気軽に GitHub Discussions が利用されています。
この記事も GitHub Discussions を利用して、チームメンバーにレビューをしてもらいました。
気軽に利用できることもあり、多くの議論が GitHub Discussions 上で行われているため、全体としては手戻りのコストが少なくなったことを感じています。
さらには、issue で議論が始まりそうな時に、「Discussions の方が適していそう」といったようなコメントが書かれ、そこから Discussions に発展していくといった当初から想定していた場面も出てきています。
解析グループにあった形に落ち着きつつあると思います。
ただ、まだまだ結局どういった場面で書くのかがはっきりしないなどの意見も出ているので、運用を続けていきながらより良い形を探し続けられればなと思います。
まとめ
GitHub Discussions で設計のレビューや実装に入る前に相談したいことを相談できる場を作り出して、それをチームにあった形で定着させていくことができました。
開発プロセスを改善していくには、チーム全員にしっかりと何を問題だと思っていて、どのような形にしていけると良いかを説明し、懸念点が少しでもあればお互いが納得できる形を取れるように誠実に議論をすることが大事だと今回の導入で感じました。
さらに、一度何か手を打ったらそこで終わりにするのではなくてチームにあった形を常に探っていくことも重要だと思います。
この記事が開発に限らず、チームとしての何かのプロセスを改善したい方の役に立てば幸いです。
Discussion