GitHubのissue、こう書かれているとめちゃくちゃ嬉しい。良いissueの書き方とは

2021年8月31日 18:38

普段プロジェクトの課題管理はGitHub運用してて、何かあればなんでもissueに書いてもらうようにしているのですが、GitHub慣れていない方や文章書くの苦手な方にとっては、

で、issueってどう書けば良いの？

という疑問が湧いてくると思います。今回はその疑問に対する回答を書きます。

issueはどんどん書こう

まず姿勢の話になりますが、issueはどんどん書きましょう。書いてダメなことはありません。少しでも「あれ？」と思ったら書きましょう。

起票者は、issueを書くことで問題点を言語化して伝えることができますし、受け取る側は、「なるほど、こういう点で困っているのか」という理解につながります。書いてダメなissueはありません。

issueを解決することは、多くの方の悩みを救うことになります。issueを解決することで、最終的にユーザの役に立つことはもちろん、運営者側としても、同じ悩みを持つユーザに最適に素早く解決策を提示することができます。

このissueを解決すれば誰が、どんなハッピーなことが起こるか想像しましょう。

それではいざGitHubにissueを作成しましょう。

issueは1日平均3〜5件、ひと月だと60〜100件上がってくる場合もあります。すると、確認する側としてはなるべく読む労力を少なくしたいとなります。

そのため、issueのタイトルを読んだだけで何をすべきなのかを書く必要があります。読む側の手間を省く努力が必要です。

🙅‍♀️悪い例
問い合わせがきた内容をFAQに追加

🙆‍♀️良い例
Kurocoでお問い合わせフォームを作る手順をチュートリアルに記載する

次にコメントを記入します。

先にコメントにどのよう内容を書いておくべきかのアウトラインを設定しておくことをおすすめします。下記を網羅しておくと、issueからドキュメントを作成する方にとって便利です。

ドキュメントの内容を詳細に記載します。手順が必要な場合は手順も箇条書きで書くとわかりやすいです。

例)
システムログイン方法を手順・画像を交えて記載する
1. ログイン画面に遷移
2. ログインフォームに情報記載
3. ログインボタンクリックする
4. エラーが出た場合の対応方法

なぜこのドキュメントを作成するのか、書くことによってどんな良いことがあるのかを記載します。

例) お客さんから***の利用方法についての問い合わせが多い。ドキュメント化し問い合わせの際の回答に利用したい。

ドキュメント作成にあたり、細かいタスクがある場合はチェックリストにして記載します。

例)
- [ ] 開発環境の準備
- [ ] テストアカウントの作成

伝えておくべきことや、補足資料があれば自由に記載します。

例:
- 先日slackで〇〇さんと議論した内容も追記したいです。（Slackのリンクを送る）
- 参考資料を添付しましたので、こちらをドキュメントよりダウンロードできるようにしてください。

アウトライン通りに書くと下記のようになります。

ちなみにGitHubではissueのテンプレートが作成できますので、テンプレートを利用して誰でも同じアウトラインで書くようにすると便利です。

次にオプションの付け方です。(AssigneerとLabelsのみ利用想定です。)

このissueの対応する人をアサインします。自分でやるのか、他の方に依頼するのかを設定します。なお、他の方に設定した場合はメンションつけてコメントすると相手が気付くので丁寧です。

このissueがバグなのか・質問なのか・提案なのかをラベル付けが可能です。ぱっと見ででわかりやすくなるので便利です。
注意：ただし、バグのラベルをつけるときは気をつけましょう。みんなバグという言葉に敏感です。

繰り返しになりますが、issueは書くだけで偉いです。ただし、書き方がよければさらに偉いです。遠慮せずにどんどんissue書きましょう。

良いGitHubライフを👋

読んでいただきありがとうございます。