開発の中でバグ報告や機能改善でIssueを書くことはよくあることですが、エンジニアになり始めの頃はどのようにタイトルを決めるのが良いのか、概要はどのように書くと相手に伝わりやすいのか悩みながら書いていました。
試行錯誤していく中で身につけていったこと、普段意識していること、やっていることをまとめてみようと思います。
※前提
・自分が所属、担当している環境ででIssueを書く場合を想定しています
・OSS等でIssueを書く際はテンプレートが指定されている場合もあるためこの限りではありません
Title
まずはTitleを決める際に意識していることについてです。最初に目に入るものであり、一覧に一番大きく表示されるものなのでTitleを決めることが一番大切だと思っています。
おすすめしない書き方
エラー内容を記載
- 「No method Errorを直す」
- 「〇〇ページのバグを直す」
エンジニアがバグ報告で一番手っ取り早くIssueを作成するには、Titleにエラータイトル、Descriptionにエラー詳細をペーストすることです。しかしこれだけでどんな対応が必要なのか瞬時に判断するのは難しく、読み手に必要以上の手間を与えてしまいます。
内容が抽象的
- 「〇〇ページの改善」
- 「〇〇の追加対応」
Titleが抽象的だと実際にどんなことを行ったのか想像ができず、リンクを押してDescriptionを見てみたら探していたIssueとは全く異なるものだった、ということになってしまいます。
長い
- 「〇〇〇〇に遷移後、×××××になってしまうことが稀にあるため△△△△△△△のロジックを□□□□□に変更したい」
Issue一覧でこのようなTitleがあってもTitleを読むだけで疲れてしまいます。情報をできるだけ書くことは大切ですが、同じ内容であれば一文字でも少ない方が読み手にとって親切です。
Titleを決める際に意識すること
1. 状態を意識する
そもそもIssueとは「問題、論点」という意味であり、問題や課題を解決させるための機能として命名されています。
私はTitleを下の式が成り立つような命名にするのが良いと考えています。
このIssueが終わる = Titleの状態になる（またはTitleが解決する）
機能改善の場合は「〜になる」、バグ報告は「〜ができない」という書き方をまず意識するだけでもこのIssueがどんな対応をしていたのか分かるようになると思います。
2. 一文字でも短く簡潔に
上にも書きましたが同じ情報量であれば一文字でも短い方が読み手は楽になります。タイトルを決める際は一度Titleを決めた後に「もっと短くかけないか？」、「他の言い回しで短く言い換えることはできないか？」を考えるようにしています。
初めは思いつかないこともあるかもしれないですが、文章表現系の本をいくつか読むと言い換え表現が浮かびやすくなります。
言葉ダイエットという本がおすすめです。
Description
次にDescriptionを書く際に意識していることについてです。DescriptionはTitleと比べて文章量が多く、自由度が広いことが書き方に困る原因になります。対処法として、自分なりの型を作ってしまうのがおすすめです。
おすすめしない書き方
URLのみ
Slack等のチャットツールで話した内容がそのまま機能改善のIssueになった場合、Descriptionに会話のURLを貼っておけば情報量としては十分ですが、何度も遷移する手間を取らせてしまいます。
それだけではなく、会話形式の場合情報がまとまっていないことも多く、内容の把握に時間がかかってしまうため会話の内容をDescriptionにまとめ直す方が読み手にとって親切です。
タスク完了の定義が曖昧
- 「登録に時間がかかっているので速くする」
このような機能改善の依頼があっても担当者はどのくらい速くなれば改善されたことになるのか分からず、Issue作成者と担当者の間で認識のズレが生じてしまうリスクがあります。
開発を終えて速度が半分になったとしてもIssue作成者は三分の一の速度を求めていた、となると開発工数が余計に増える原因となってしまいます。
とにかく書く
要望があった場合に考えていることをとにかく書いてみると、状況を把握している自分自身は文章を読んで理解することができますが、前情報の無い他の人は理解に時間がかかる、または理解できないことがあります。
Descriptionを決める際に意識すること
1. タスク完了の条件を具体的に書く
- 「現状の半分の速度で更新できるようになる」
- 「複数アカウント作成できるようになる」
タスク完了の条件を書き、またその条件も具体的に書くと認識のズレがなくなります。どちらの例も「〜になる」という文章になってるように、タスク完了の条件とTitleは近いものになることが多いです。
2. テンプレートを用意する
読みやすいDescriptionを書く一番のコツはテンプレートを用意することです。項目を埋めていくだけで情報が整理されるので長い文章を書くのが苦手でもDescriptionを書きやすくなります。
私は「As-Is/To-Be」分析を参考にしてテンプレートを作成しています。
テンプレート例
### As Is
（今の状態を記載）
### To Be
（理想の状態を記載。タスク完了の条件にもなる。）
### アクション
（改善のための具体的なアクションを記載）
### 課題
（現状分かっている課題を記載）
テンプレートは保存しておくと便利
GitHubにはIssueテンプレートを設定する機能があります。
設定しておくとIssue作成時にテンプレートを指定できるのでおすすめです。
私はテンプレートをツールに依存せずに使いたいのでClipyというスニペットアプリにテンプレートを保存していつでもペーストできるようにしています。
登録、更新も簡単でショートカットですぐに呼び出せるので気に入っています。
まとめ
私がIssueを作成する際に意識していることをまとめてみました。リモートワークが主流になった今、文章で伝えるスキルがより一層大切になっていると感じています。これからも伝えるためのより良い方法を模索していきたいと思います。