ページ2016.08.18プロジェクト管理Issueを書く際の心構えshimo弊社ではIssue管理ツールとしてGitHubのIssueを利用しています。Issueは以下のようなフォーマットをプロジェクトの.github/ISSUE_TEMPLATE.mdに登録しておくことで、GitHubでIssueを立てたときに自動的にひな形が補完されるようにしています。その他・備考ただ、最近佳境にあるプロジェクトもあるせいか?、曖昧(適当?)に書かれているIssueがたまにあり、私自身も、時間がないときにとりあえず急いでIssueを立てておこうとして、分かりづらいIssueになってしまっていることがあります。分かりづらいIssueは以下の様な弊害をもたらします。実装者がIssueを立てた人に意味を再確認しないといけない。実装者がIssueの内容を捉え誤って、間違った実装をしてしまう。レビューする人がIssueを参照しても、何を実装したかったのか分からない。Issueをきちんと書くにはそれなりの時間がかかることもありますが、上記デメリットを解消できることを考えると、そこに多少の時間をかける価値がある場合も多いです。今回は自戒の念も込め、実際にあったイマイチなIssueをデフォルメした上で、Issueを書く際の心構えについて書きたいと思います。これはもちろんGitHubに限らず一般的なチケット全般に言える話でもあります。ContentsタイトルコメントまとめタイトルIssueの一覧を見るときにはタイトルを見ることになるので、タイトルを見てどういう内容かを把握できるように簡潔に書くことが大切です。Balancerのことを言っていますが、これはお互いに共有している前提でお話しします。上記タイトルはコンテキストを共有している人だったら分かるかもしれませんが、共有していない人には誤解を与えてしまうかもしれません。分かりにくくなっている一番の要因は、「無視する」という言葉でしょうか。「無視する」という言葉は主語と目的語を要求しますが、主語が書かれていません。タイトルでは主語は省略されることは一般的ですのでそれ自体はいいのですが、一般的に「無視する」というのは「人が無視する」という場合に使われることが多いのではないかと思います。人が目視か何かでログを無視するのか、それとも何らかのプログラム的に無視するのか、もしくは他の何かが無視するのかが分からず混乱してしまいます。細かい話ですが、「health_check」というのはおそらくELBからのヘルスチェックのことを言っているのだろうなとは想像できますが、「health_check」という一般的な単語はありません。「Railsのアプリケーションログに、ELBからのヘルスチェックのアクセスが記録されていることがイヤなので、ヘルスチェックのアクセスをロギングしない対応をする。」というところでした。「RailsアプリケーションログにELBからのヘルスチェックアクセスをロギングしない対応」などといった改善案が考えられます。タイトルは簡潔にかつ的確に書く必要があり、言葉をうまく選ぶことが大切だと思います。コメント機能エンハンスの場合を取り上げます。APIは誰が使うAPIなんだろう?API仕様から決めるのか、API仕様は決まっていて実装するだけなのかどっちだろう?API仕様から決めるんだったら、何を参考にして決めればよいんだろう?API仕様があるんだったらどこにあるんだろう?上記のような情報は追加する必要があるでしょう。API」というのは若干苦し紛れに書いた(埋めた)と思われますが、意味のない情報ですのでそれだったら書かないほうがいいかと思います。それを踏まえてちょっとだけ修正するとこんな感じでしょうか。(実プロジェクトと関係ない架空のストーリーなのでなかなか書くのが難しいですが、実プロジェクトだともっと情報が必要になってくる場合も多いと思います。)また、Issueがバグレポートの場合は違った内容が必要になりますが、また別の機会に。まとめ分かりやすいIssueを書くのは奥深いものです。結局、一番大事なことは読む人の立場になって文章を書くというところだと思います。書いた後にさっと読みなおして、他の人に分かるかなと考えるところから始めるところから始めるのもいいのではないでしょうか。ウェブサービス株式会社(DWS)公式ブログ記事URLをコピーしました。