こんにちは。開発部エンジニアの石上です。最近は息子とプラレールで遊ぶのが楽しいです。先日、社内のSlackでおすすめされていて気になっていた自動ターンアウトレールなるものを買ってきました。走るごとに進行方向が切り替わって、とても楽しいです。
さて、今回はGitHub Discussionsによって開発チーム間の非同期コミュニケーションを実現した取り組みについてご紹介します。新しいプロジェクトで仕様を固めるのが難しい、開発者が多くてAPIの認識合わせに時間がかかるなど、新機能開発時の認識合わせで困っている方に、こういうやり方もあるのかと参考にしていただけたら幸いです。
3行で
忙しい方向けの3行要約です。興味があったら中身も読んでみてください。
- 開発の認識合わせが難しい
- GitHub Discussionsで相談や議論しながら進めた
- 非同期かつ図を用いたコミュニケーションで効率的に認識を合わせることができた
背景
10月に、教材配信システムをリリースしました。本記事は、この機能開発でAPIの仕様を決める際のコミュニケーションのとり方についての話となります。
教材配信システムについて詳しくは、以下のnote記事をご覧ください。
教材配信システムは、Studyplusという既存のアプリ上で問題を解いたり解説を読んだり回答の正誤を確認できる機能です。
こう書くと、単純な新機能という感じで、少人数で相談しながらサクサク作れそうな気がします。ところが、実際にはStudyplusアプリ、Studyplusのバックエンド、Studyplus for School（塾向けのSaaS）、そして今回新たに作るDrill（教材配信システムのことを社内的にこう呼んでいます）の4つのシステムにまたがるプロジェクトとなりました。
簡易的に示すとシステム間で以下のような連携が発生しています。
それぞれのシステムにそれぞれのチームがあります。Studyplusアプリにはモバイルクライアントチームが、Studyplusのバックエンドにはサーバーチームがいて、Studyplus for SchoolにはForSchoolチームがいます。
教材配信システムのチームには3人のエンジニアがいました。Studyplusアプリ・Studyplusのバックエンド・Studyplus for Schoolから１人ずつ招集される形で編成されていたため、それぞれのシステムと調整しやすい配置になっていました。
課題
しかし、調整しやすい配置とはいえもちろん課題もありました。 教材配信システムの開発中であっても、当然各システムも並行して保守や開発が行われています。 各システムからそれぞれメンバーを招集して構成したチームとはいえ、教材配信システムチームだけで連携方法を決めるわけにはいきません。 各システムのチームとの調整には、教材配信システムチームのコンテキストを共有したり、これからやりたいことをわかりやすく示す必要があります。
ForSchoolのチームと相談を始める際、私はざっくり書いたシーケンス図を持っていき、こういうAPIのやりとりをしたいがどうかと尋ねるミーティングを行いました。結果、そもそもデータの前提がわからない、やりたいことがよくわからないといった反応を受けてそのミーティングは終了してしまいました。
システム間の連携方法としてどういったデータの持ち方にするか、APIのやりとりにするかにはいくつも選択肢があり、前提ややりたいことによってどれを選ぶといいかは変わってきます。共有されてるコンテキストが違うチーム間で、口頭でそれらをうまく議論するのは難しいと感じました。
きっかけ
上記のミーティングの際、こういったやりとりはGitHub Discussionsで行いたいという話を受けました。まずForSchoolチームとの連携でそれを利用し始めて、効率的にAPI仕様の相談を進められることに気がつきました。どうせならそこに統一しようということでクライアントサイドとの調整にもこれを使うようにしたところ、うまくいきました。
GitHub Discussionsとは
GitHub Discussionsとは、GitHub上で質問に対する回答を募ったり、アイデアを共有したり、議論ができたりするGitHubの機能です。
OSSコミュニティでも多く使われていたり、GitHub自体の機能に対するフィードバック先としても使われています。たとえばGitHubの機能に対するフィードバックを、以下のようにDiscussionとして登録できます。
GitHub issuesを使ったことのある方からすると、見ての通りissuesと見た目はほとんど変わりません。ただ、議論の結論をハイライトしたり、コメントにupvoteしたりと、Discussionsならではの使い勝手が実装されています。
プライベートリポジトリでも使えるので、仕事でも使うことができます。これを今回、チーム間のやりとりで使おうということになりました。
進め方
今回の進め方としてはこうです。
- GitHub Discussionsにデータの前提とAPIでのやり取りの提案をざっくり書く
- 相談したいポイント、考えられる他の選択肢などを書いておいてコメントを募る
- 提案の通りでいいよという場合は絵文字でリアクションしてもらう
- 結論が出たらそのdiscussionにdiscussedラベルを付ける
- OpenAPI（Swagger）を記載したPull Requestを作ってより詳細にレビューしてもらう
- API仕様に則って各々が実装を進めていく
自分の提案が最初から完全に正しいことは稀なので、あくまでも相談として投げるようにしていました。実際、Discussionsを経て、当初検討していたAPIの開発が丸々不要だったということもありました。
実際の様子
実際の様子はこんな具合です。
これはクライアントサイドとの調整の様子なので、仕様の把握がしやすいように、関係する画面のスクリーンショットを持ってきて、どこにそのやり取りが発生するかがわかるようにしています。また、GitHubではMermaid記法がサポートされているため、簡単なシーケンス図を書くことで、具体的なやり取りを提案しています。
Mermaidの良さ
簡単なシーケンス図やER図でも、あるのとないのではだいぶ違います。GitHub DiscussionsではコメントもMermaid記法で書けるため、議論の途中でも図を挿入できます。文章で書くと複雑に感じることも、図示することでわかりやすく伝えることができるので、こういった仕様調整の場には不可欠だと感じています。
会議が減ることの良さ
もしもすべての関係者と毎回会議をしていたら、おそらく一日のほとんどを会議で埋め尽くすような状態になっていました。API仕様の調整を非同期にすることで、お互いが待ちの時間を有効活用できました。
フィードバック
プロジェクトの振り返りでも、GitHub Discussionsの利用が良かったと振り返っている方が多かったです。
Discussionsでの設計や実装の認識合わせはesaより議論がしやすくSlackより見返しやすいので今後も使っていってよさそう
GithubのDiscussionsを用いることでサーバとアプリの並行開発が実現できた
Discussionsがスムーズにやりとりでき、開発できない時間が少なかった
Discussionsに議論を残してくれていたので、決まった経緯が把握しやすかった
仕様面などの相談事がGitHub上のDiscussionsで纏められて確認がしやすかった
一方、GitHub上だとビジネスサイドのGitHubアカウント持ってない方は見えないというフィードバックもありました。
DiscussionsはGitHubアカウントない人が見れない
開発面の相談から広がって仕様の相談になったりもしていたので、そこで決まったことがGitHubアカウントのない人からは見えないのはたしかに問題です。
議論にDiscussionsを利用する範囲を開発面の相談に絞ったり、それでもビジネスサイドへの影響があるものが出てきたら別途共有するなど、工夫が必要そうです。
まとめ
GitHub Discussionsを用いた非同期コミュニケーションについてご紹介しました。今回はこのような形でうまくいきましたが、やり取りが単純だったり、同じチーム内であれば同期的なコミュニケーション（口頭やSlack）でちゃちゃっと認識合わせしてガッと作ってしまう方が良い場合もあります。
しかし、複雑なやりとりを決定する必要があって、焦らずじっくり、でも効率よくコミュニケーションをするためには今回ご紹介したようなやり方が合っている場合もあります。今後も状況に合わせて工夫しながらやっていけたらと考えています。
