📚

チーム開発で『GitHub Discussions』を運用してみた

2022/06/23に公開

はじめに

チーム開発でのチャットなどのコミュニケーションで、こんな経験はないだろうか?

「チームの知見や話題が整理されていない…」
「大事な話題があったけど、チャットで流れて忘れ去られていた…」
「あの話題ってどうなったっけ?」
「議論したことを構造化してログに残すのがめんどくさい…」

僕は全部あります。

この記事では、そういった不便な経験を解消すべく、考えた末にたどり着いた『GitHub Discussions』の運用設計について解説していきます。

運用方法

まず、GitHub Discussions(以下 Discussions)の運用で達成したいことを明確にしました。

  • 過去ログのデータベース化
  • 埋もれてしまう事前調査・知識の蓄積
  • 議論を構造化して議事録にする手間の解消

また、今回の運用の特徴として、エンジニアだけでなく他の業種も一緒に運用しています。
もともと、チャットで行っていた異業種間での議論を Discussions で行ってログを残したかったからですね。

こうすることでプロジェクト全体の議論等のログが Discussions に集約され、プロジェクト全体で話題の検索性が向上します。

カテゴリ

話題の内容をザックリと分けることができるカテゴリ機能があるので、まずは Discussions でどのような話題について話し合うかを決めます。

今回の設計ではこのようなカテゴリを用意したので、それぞれの役割について説明します。

はじめに

これは基本的に Discussions の使い方についてのディスカッションを作成して、チームメンバーに伝えるために使用されます。

また、作成したディスカッションをピン止めすることで、目立つ場所に Discussions の使い方を表示させることができます。

アイデア・提案

「ここはこうしませんか?」といったような提案を行い、議論をするためのカテゴリです。

プランナーに対して「この仕様はこうした方が良いんじゃないか?」といったような話を持ちかけることが多く、このカテゴリによって仕様についての議論がログとして残りやすくなるのは仕様管理の面で非常にありがたいです。

質問・相談

「ここはこういう認識で合ってる?」といった確認をとったりするためのカテゴリです。

そこからさらに掘っていくことで、機能の詳細を詰める議論に発展することもあります。

調査・検討

「この機能はどうやって実装すればいいのか?」といったような調査・知見をメモするためのカテゴリです。

今まではチャットで流れてしまっていたのが、確実に知見として蓄積されていきます。

みんなで議論

プロジェクト全体の事について議論できるようにするために作りましたが、まだ使っていないです。(もしかしたら要らないかも)

ラベル

以下のようなラベルを用意しているので、話題に応じたラベルを貼ります。(複数選択可)

  • エンジニアリング
  • 3D
  • デザイン
  • UI / UX
  • プランニング

仕様管理用のラベル

プランナーとの議論の結果で仕様が修正される事が多く、特殊ラベルとして 仕様:要修正 仕様:OK のラベルを用意しました。

これはプランナーが仕様修正の管理を行う際に使用するもので、以下のような使い方をします。

  1. 議論で仕様の修正が決まったら仕様:要修正 ラベルを貼る
  2. Notion 等の仕様書に新しい仕様が適用されたら仕様:OK ラベルに置き換える

Discussions には、ラベルでディスカッションを絞り込める検索機能があるので、これで仕様修正の把握が容易になります。

ルール

「はじめに」カテゴリに作成した、Discussions の使い方を説明するための「投稿前にご確認ください🙇」を参照してもらうようにしています。

「投稿前にご確認ください🙇」の内容は、現時点で以下のようになっています。

「投稿前にご確認ください🙇」の内容

はじめに

このDiscussionsは以下の目的を元に設計されています

  • 過去の質問、議論ログの一覧性、検索性の向上
  • 埋もれてしまう調査、知識の蓄積
  • 質問、議論を質問シートに起こし直す手間の解消

GitHub Discussions自体、正式リリースから1年にも満たない若い機能なので、探り探りで運用することになります。
運用の改善点等あれば、どんどんフィードバックをください!

起票(ディスカッションの作成)

起票の基準

  • カテゴリに該当する話題があれば起票する
  • Chatwork等のやり取りの中で、Discussionsに起票した方が良いと思ったことは起票する(会話のリンクを添付しよう)
  • 小さすぎる、特殊過ぎる、一般的すぎる内容は起票しない(過去ログのノイズが増えるため)
  • Discussionsは検索機能が充実しているため、起票する前に過去ログを検索してみましょう

カテゴリ

その話題に当てはまるカテゴリを選択しましょう(後から変更可)

「質問・相談」「アイデア・提案」カテゴリには、ディスカッションを「回答済み」としてマークする機能があるので、最終的な回答が出た場合には 「質問者側」 が回答をマークしましょう。(検索性向上のため)

Webでは「Mark as answer」、アプリでは「✔マーク」を押すことで回答をマークすることができます。
(返信は回答としてマークできないので、回答をする際は「返信」ではなく「回答」でお願いします)

タイトル

内容が分かるようなタイトルを付けることを心がけましょう(後から変更可)
特定の機能に関するディスカッションを作成する場合、タイトルの冒頭に【○○】と付けると一覧性・検索性が向上します。

例:【レンダリング】キャラクターの影の実装方法をどうするか?

ラベル

その話題に当てはまるラベルを貼りましょう(複数選択可)(後から変更可)

ラベル 使い方
エンジニアリング 機能の実装方法についての話題など
3D モデリングなど3Dに関する話題など
デザイン UIのデザイン等についての話題など
UI / UX UIのレイアウトや挙動に関する話題など
プランニング 企画、仕様に関する話題など

本文

  • @マークでメンションをすることで通知が飛びます(例:@mackysoft)
  • Markdown形式を使用可能です

田中チェック

(田中は仮名です)

基本的に、エンジニアリング以外のディスカッションでは田中チェックを行います。

以下のカテゴリに該当する

  • アイデア・提案
  • 質問・相談

かつ、以下のラベルが貼られている

  • 3D
  • デザイン
  • UI / UX
  • プランニング

以上のディスカッションで話がまとまった場合は、「回答に対して同意した側」が田中に対してメンションで確認を促してください。
田中の確認ができ次第、最終的な結論がディスカッションの回答としてマークされます。

回答に対しての指摘等があれば、最終的な結論が出るまでディスカッションを継続します。

過去ログの参照

  • Discussionsは検索機能が充実しているため、起票する前に過去ログを検索してみましょう
  • もし質問された場合は、出来るだけ過去ログのURLを貼りましょう

チームに定着させる試み

場所を作っただけでは、チームに根付かないまま忘れ去られて終わります。

そこで、Discussions をチームに定着させるための試みをいくつか紹介します。

ルールを参照しやすいようにする

上記で説明したように、Discussions の使い方についてのディスカッションを作成してピン止めすることで、トップ画面に大きく表示し、メンバー全員が Discussions の使い方を周知できるようにしました。

見本となるディスカッションを作成しておく

各カテゴリに最低1つ以上の、見本となるディスカッションを作成することで、他のメンバーが迷いなくディスカッションを作成できるようにしました。

起票すべき話題があれば Discussions に誘導する

チャットで起票すべき話題が出てきた場合は、「この話題はディスカッションで残しておきたいです!」といった具合でディスカッションを作成するようにお願いし、「Discussions を使用した」という経験をしてもらいます。

メンションで Discussions に引きずり込む

@マークを使ってメンションし、質問や議論を投げかけることで特定の人物を Discussions に引きずり込みます。上記と同様に「Discussions を使用した」という経験をしてもらいます。

実際に運用して感じたこと

複数の話題を同時に起こして議論できる

Discussions では話題ごとにスレッドが作成されるので、話題が一覧として表示されます。

タイムライン形式のチャットだと、新しい話題が始まると同時に古い話題は流れていってしまうのですが、Discussions では同時並行で別の話題について議論を行うことができます。

議論の結果を保留できるようになった

例えば、議論中に出てきた事柄を検証したいとなったときには議論が一時停止します。

チャットのタイムラインだと保留した議論が途切れ途切れになってしまって話題を追いかけるのが大変でしたが、
スレッド形式になっているので、議論が一時的に止まったとしても話がきれいに繋がります。

下手すると保留した議論が流れてしまって議論自体が忘れ去られることもあったのだけど、Discussions は一覧性が高くて数週間前の話も簡単に追うことができます。

通知はそんなに強くない

メンションをすれば GitHub アプリからプッシュ通知が届きますが、そうでなければ基本的にメールで通知が届きます。

そのため、「メール -> GitHub アプリ」といった感じで2アクション必要になります。
情報としては問題ないので、使っている感じではそこまで問題は感じていないです(個人的には)

ちなみに Slack を使っているのであれば、GitHub Actions と連携してなんとかできるらしい。

【GitHub Actions】GitHub DiscussionsをSlackで通知する

さいごに

GitHub Discussions の運用についての解説は以上になります。

GitHub Discussions の運用設計をしていて感じたのは、アプリの運用と変わらないということです。

チームのみんなが利用する導線があって、分かりやすくて、便利で、もう一回使いたいと思えるように設計すれば、チーム全体に浸透していくのだと考えています。

参考

GitHubで編集を提案

Discussion