CARTA fluct エンジニア の なっかー @konsent_nakka です。
私のチームでは2024年7月ごろからGitHub Discussionsを運用しています。
運用の結果、感触が悪くなかったので共有がてら記事にしました。
GitHub Discussionsとは
プロジェクトに関するコミュニティの共同コミュニケーションフォーラムです。 コミュニティメンバーは、質問をしたり、質問に答えたり、最新情報を共有したり、自由形式の会話をしたり、コミュニティの動向に影響を与える決定をフォローしたりすることができます。
https://docs.github.com/ja/discussions/quickstart
想定読者
- 知識が流れてしまって貯まらないチーム
- slackに投稿されたままいずれ見つけられなくなる
- 一覧性が良くない
- 知識を貯めることはできるが更新されず混乱を招いてしまっているチーム
- リポジトリ内のdocs/ディレクトリやwikiに書いてもすぐ変化してしまうが更新を忘れるし大変
- Issueに書いてしまうと通常のタスクと区別がつかなくて整理が難しい
伝えたいこと
- GitHub Discussionsをお試し運用している
- GitHub Discussionsは気軽に書けて、流動的な知識の共有に良い
- 他にもおすすめの運用があればみんなで共有しよう
話さないこと
- GitHub Discussionsの仕様、利用開始方法など
運用してみてどうか？
最初の動機としてはアプリケーションの引っ掛かりポイントやTipsを共有する場所が欲しいというものでした。
今まではslackで教えてもらってそのままや、Issueにメモとして残しておいたり、wikiに記述したり、方法はバラバラでした。slackに書くだけでは流れてしまうし、Issueに書いたらそれをcloseしづらかったり、wikiは編集されないなど、通常のタスクと見分けづらくゴチャついた印象になってしまいます。
そこでDiscussionとして記載するといくつかの利点があります。
- Issueはタスクだけを記載できるようになる
- DiscussionにAnswered設定ができて、解決策が出ているのか出ていないのか一目で分かる
- カテゴリ設定やラベル設定をしてフィルタリングできる
どんな運用をしているのか？
実際のプロジェクトにも記載している、GitHub Discussionsを運用する目的は以下の通りです。
- 過去の質問、議論ログの一覧性、検索性の向上
- 埋もれてしまう調査、知識の蓄積
- 質問、議論を質問シートに起こし直す手間の解消
起票の基準も記載してあります。
- リポジトリ、リポジトリに含まれるプロダクトの注意点を共有しましょう
- 疑問に思っていることを質問してください
- Slack等のやり取りで、Discussionsに起票した方が良いと思ったことは起票しましょう
- 会話のリンクを添付しよう
- Discussionsは検索機能が充実しているため、起票する前に過去ログを検索してみましょう
使い方としては、Issueやdocs/に記述する前のホップにしている感覚です。
チームへの説明
使用目的やチームとして推奨している使い方を「はじめに」として作成しています。さらにページトップにPinしているので、新しいメンバーが入った時もすぐに閲覧できるようになっています。
カテゴリ
カテゴリを自分で決めて、カテゴリに対してDiscussionを投稿する仕組みになっています。
カテゴリをあまり分けない方が投稿障壁は下がると思うので、今の所は実質2個しか作っていません。
まとめ
- Issueのタスクと分けて記載できる
- DesignDocなど
docs/に置くほど明確なドキュメントにするほど頑張らなくて良かったり、すぐに変更される可能性のある情報、をとりあえず残したいときに使いやすい - 一覧性、検索性が良い
- Answeredが付いてるかどうか分かるのも良い
- Answeredを設定出来るか出来ないかもカテゴリ作成の時選べる
