GitHub WikiとDiscussionsのご紹介

GitHub上の情報共有に「Wiki」「Discussions」があります。本記事は両者についての概要や簡単な操作などをご紹介します。

※Freeプランの場合、WikiはPublicなリポジトリじゃないと有効化出来ません。

GitHub Wiki

概要

GitHubの場合、リポジトリ単位にWikiを使うことで、リポジトリに関するルール等を文章化出来ます。

ウィキでプロジェクトを文書化する - GitHub Docs

ウィキを使用してプロジェクトに関する具体的な長文形式の情報を共有できます。

docs.github.com

例えば、次のようなルールをページ単位に文章化することが考えられます。

• リポジトリの概要
• リポジトリのブランチやコミットルール
• ビルドの手順

等です。

お試し

ページ作成

リポジトリ作成後、Wikiメニューよりページ作成を試します。

最初のページのデフォルト名は「Home」です。

ページの作成が出来ました。

以下の画像では「Home」以外に「ビルド手順」「リポジトリの運用ルール」といったページを追加しています。Pagesにまとめて表示されます。

補足です。

• ページ書式はMarkdown等で指定可能です。
• ファイル添付可能です（容量は種別制限有）。

サイドバー

Wiki画面右側のサイドバーを使うと、任意ページだけをサイドバーに表示させたり、ページの階層表示が出来ます。

# 一例（Markdown書式）
・ページのリンク設定は [[ページ名]] のように囲みます。
・階層は * を使います。

階層表示を試すため、サイドバーを次のように指定します。

 * [[Home]]
   * [[リポジトリの運用ルール]]
   * [[ビルド手順]]

無事に階層表示になりました。子ページは「*」の前にスペースを2つ追加しています。

• サイドバーを追加するとPagesのデフォルトは折りたたまれます。
• ページのタイトルを変更した場合、サイドバーも合わせて変更しないとリンク切れになります。

出来ないこと

次のような操作は出来ません（一例）。

• 特定文章や全体に対してコメントする。
  → Wikiは議論する場所ではないためDiscussionsを使いましょう。
• ドラッグ＆ドロップでページの階層化
  → ページ数が多いと大変かもしれないですね、計画的に進めましょう。
• ページ毎に閲覧権限
  → Wikiはリポジトリ権限と同じ粒度です。

これぐらいの制約であれば、簡易的にリポジトリルール等の共有を行うには十分です。

※もしも、リポジトリを超えて高度に文章管理等を行うのであれば、別の管理ツール（シェアポイント等のグループウェア）を使うなどしましょう。ExcelやWordをGitHubで管理する手も無くはない。

GitHub Discussions

こちらは簡単に言うと、アイディアや質問内容を議論できる場所です。

GitHub Discussions のドキュメント - GitHub Docs

GitHub Discussions は、オープンソースまたは内部プロジェクトに関するコミュニティの共同コミュニケーション フォーラムです。 コミュニティメンバーは、質問をしたり、質問に答えたり、最新情報を共有したり、自由形式の会話をしたり...

docs.github.com

お試し

早速試します。

リポジトリの設定でDiscussionsは無効となっていたため、まずは有効にします。

Discussionsがメニューに表示されたため、「New discussion」より作成してみます。

色々なカテゴリ（General, Ideas, Polls, Q&A, …）で作成出来ますが、今回は「Q&A」を選択して作成します。次の画像では作成した後にコメントしたりしてみました（自己回答ですが）。

投票に特化した起票で「質問内容」や「選択肢」を定義して、結果を集計できるようになっています。

カテゴリによって画面のフィールド配置が違ってくるんですね。

なお、「Q&A」はanswerをマークすることが出来ます。イイネ相当のボタンは共通して存在するため、トピックの盛り上がり具合を測ることも出来ます。

Issuesとの違い

Issuesでもチケット単位のコメント機能によって、議論は可能です。

しかし、簡単な質問内容などもIssuesに表示されると、正直ノイズです。Issuesではリポジトリの変更に関わるものだけを管理したいのです。

それにDiscussionsであれば、カテゴリ（質問やアイディア等）を分けることが出来ますし、投票機能などによって人気の度合いも測定出来ます。使い分けたほうが確実にわかりやすく管理出来るはずです。

また、議論の結果、実装しようとなった場合にIssuesに送ることも出来ます。この場合、元の議論は停止され、Issueにはどのディスカッションから作られたのか確認出来ます。

あと、Organizationを利用している場合は、Organizationという単位でDiscussionsが出来るようになっています。Projectsのようにリポジトリ横断型が必要な背景だと思ってます。

補足事項

◇ファイル添付は可能。
→ ファイル種別や容量の制限あるけど、ドラッグ＆ドロップで添付出来ちゃう。なお、添付ファイルの「実体」削除はGitHubサポートを絡める必要があります。そうしないとURL知っている人はアクセス出来ちゃいます。

◇Team Discussionsは廃止
→ Team単位のDiscussionsは2023年5月に廃止とのこと。代わりにOrganization単位のDiscussionsを2022年にリリースしたから、そっちで引き続き活発に議論してねってことみたい。（Sunset Notice – Team Discussions | GitHub Changelog）

◇Wikiの編集コンフリクトは検知可能
→ 編集中に他の人が保存した場合は「Someone has edited the wiki since you started. Please reload this page and re-apply your changes.」と表示される。この場合、編集内容を退避して、再読込して再編集しましょう。

まとめ

今回はGitHubでの情報共有手段としてWiki、Discussionsをご紹介しました。

• Wikiは手順書等の文章を共有出来ます。
• Discussionsは様々なテーマ（カテゴリ）毎に質問、議論、投票などが出来ます。

GitHubだけに完結して色々なことが出来るのは本当に便利です。いろんなツールを触る必要がないってのは省力化にもよろしいと思います。