Issue管理システムを使っている開発現場では同僚の書いたチケットに悩まされる以下の様な光景が良く見られます。
事例１「何の目的で作られたのか分からないチケット」
ソースレビューを振られたのでチケットを見てみたら、何を変更したいかは分かるけどこの変更がどういう意味があるのか分からないケース
担当者の対応
作業したメンバーの席まで歩いて行って
「ねーねーこれさー、何のために作ったの？」
「あーそれはですね、まず○○という話がありまして、それで…」
（背景から説明されて１５分経過）
事例２「ソースを全部読まないと何を変更したか分からないチケット」
ソースレビューを振られたのでチケットを見てみたら１０コミットぐらい入れてあるけどチケットの説明が簡素過ぎて何の仕様をどう変更したか（もしくは新規に作ったか）がソースの差分を全部読み込まないと分からないケース
担当者の対応
作業したメンバーの席まで歩いて行って
「ねーねーこれさー、要するに何変えたの？」
「あー、ちょっと待ってもらって良いですか？（いっぱい変えたからすぐ出てこない…）」
（思い出して変更点を列挙するまでに１０分経過）
事例３「意味がわからないチケット」
誰かが切ったチケットを振られたのはいいけど何が書いてあるか分からないケース
担当者の対応
チケットを切ったメンバーの席まで歩いて行って
「ねーねーこれさー、何？」
「あー、これ別のチケットから派生して作られたんで良くわからないっすねー」
「Ａさんが詳しいはずだからAさんに聞いてみましょう」
Ａさん「良く分かんないからＢさんにも聞きましょう」
Ｂさん「いや俺知らんし」
運が悪いとドラクエの如くいろんな人の所にタライ回しにされ１時間近く彷徨うハメになります。
事例４「後になって振り返ると全然分からないチケット」
チケットは正常に処理され、作業者とレビュアーは合意が取れておりすでに本番にリリースされているのに、第三者がそのチケットを読んだだけでは内容がサッパリ分からない。
しかしその修正で障害が発生したので担当者を問い詰めなければいけないケース。
当事者の対応
作業したメンバーとレビューしたメンバーの席まで走って行って問い詰めるが当人達も覚えていなくて全社を巻き込んで泥沼化する
→最悪殴り合いに発展
何が原因か？
Redmine、Backlog、JIRA、GithubといったIssue管理システムを使う最近の開発では、個々のチケットを通じて相手に作業依頼をするケースが多くなります。
口頭やメールで依頼する内容をつらつら書いたりすることなく、Issue管理システム上でチケットの担当者を変更し、Issue管理システムから飛んでくるメールで作業を依頼されたことを周知させている現場も多いのではないかと思います（少なくとも自分が関わった現場ではそうでした）。
そのため、他人に意思を正しく伝えるには、チケットに必要な情報が十分に掲載されている必要があります。
そうしないと上記のように、作業を振られる度にいちいち担当者の所まで行って質問しに行かなければならず、質問しに行ったついでにあれやこれや雑談していると簡単に１０分、１５分を無駄にしてしまいます。チーム内で同じことがどこかで毎日起きていたら間違いなくチーム全体の生産性の低下につながります。（そして何故か問題として取り扱われにくいですコレ）
どうするか
そんな重大な問題を引き起こしかねない一方で、上記の事例は全て「チケットの書き方」をちょっと改善することで大方解決できそうな問題です。
以下に説明する「ちょっとした気遣い」程度のことで、チームの生産性を大きく向上させることが出来ると信じています。
伝わりやすいチケットを書く上で自分が気をつけていること
現職ではGithubをIssue管理に使っていますが、IssueやPullRequestの説明やコメントを書くときに以下のことに気をつけています。
背景、目的、作業内容を必ず書く
簡単でも良いのでこの３点を押さえていれば、プロジェクト内の第三者が読んだ時に困ることは無いと思います。
この３点さえ抑えれば他の事は自ずと導かれてくるはずです。
しかし残念ながらこの３点すら書かれていないチケットを数多く目にし、その度にチケットを切ったメンバーの所に「そもそもコレってどういう話ですか？」という所から問答をスタートしなければならないケースが多々ありました…
例
＜背景＞
ユーザー新規登録画面においてページ離脱率を向上させる施策を実施したい。
そのために入力フォームがどのくらい入力された段階で離脱したかを知る必要がある。
＜目的＞
ユーザーが離脱した時点でどの入力フォームが入力済みであるかを知る。
＜作業内容＞
Google Analyticsのイベントトラッキングで以下のイベントを
トラッキングできるようにjsを仕込む。
TODO:
・入力フォームに入力してfocusが外れた時。未入力時は飛ばさない
(個々のinputタグのnameと入力された文字数をGoogle Analyticsに飛ばす）
・確認ボタンのonsubtmit
・ページ離脱(beforeunloadにbindする)
Redmineを使ってる場合はIssue Templateプラグインを入れてテンプレートとして上記のような項目のタイトルを入れておくと良いと思います。
また、Githubの場合はタスクリストをチェックボックスで作ることができるので、PullRequestの場合は必ず説明文に入れています。
画像で表現できるものは必ず画像を貼る
web画面やスマフォアプリ等でGUIがあるアプリの場合、必ずキャプチャを貼ります。
口で「UserControllerのlistで表示される画面の上から３番目のtableでさ～」なんて言われても分かりませんが、
キャプチャ取って丸つけとけば一発です。百聞は一見に如かずと昔の人は言いましたが今でも通用します。
文章では伝わらないことが画像や絵なら一発で伝わることも少なくありません。面倒臭がらずに画像に頼りましょう。
私はwebのキャプチャを取るためにChromeExtentionのAwesome Screenshotを使っています。
全体キャプチャ・部分キャプチャ・トリミングだけでなく、文字の表示や、四角・丸などで該当箇所を囲んだりといった加工がブラウザ上でできます。最近なんか挙動が怪しいですが、とりあえず使えてます。
あとはMacだったら画面の動作をQuickTimeでキャプチャしてGifアニメにして貼るのもオススメです。
チケットの説明文に書く情報は出来るだけ沢山
バグチケットの場合だと情報が多すぎて困るケースは殆んどありません、というか多分ないです。
バグ調査の情報として載せられるものは何でも載っけましょう。
私の場合は以下をよく載せています。
- サーバサイドのエラーログ
- 問題を引き起こしてるSQL
- 問題が起きている画面のキャプチャ
- 問題が起きた際のmysqlの
show full processlistのログ
- 関連する資料ファイル（Excel,pptなどの外部ファイルがあれば）
- 関連するチケットへのリンク
自分の作業メモをチケット上に残す
実践している人が意外とあまりいないtipsですが、自分がチケットを作ったり実際に作業している際に考え方こと、仕様決定で迷ったことなどをチケット上に残しておくと、レビュアーやテスター対してコミットの意図が伝わりやすくなります。
後で作業者や起票者の「思考をトレース出来る」というのは文章によるコミュニケーションの大きな利点ですので活用しない手はありません。
ただしあまり沢山書くと邪魔になってしまうので、ある程度バーっと書いてからあとで整理しておくのがオススメです。
自分の場合は以下の様なものをチケットに書いています。
- 自分が手を入れている部分の仕様メモ
- 疑問点とそれに対する回答（自分で聞いて回って解決したら回答を付け足しておく）
- 実装中に「これでいいのかな？」と思ったこと（あとでレビュアーにレビュー依頼時に重点的に見てもらうために）
- 設計の意図
- 作業中に作った画面のキャプチャ（作業中は自分が見る用に、レビュー/テスト時はレビュアー/テスターが分かるように）
最後に
こういう話をすると高確率で「めんどくさい」「うちのチームは誰もチケットの内容なんて誰も読まない」 「Face to Faceで十分会話してるから問題ない」とか何とか言われます。
しかし、ちょっとやってみれば分かりますが、チケットを切る際に背景・目的・作業内容の３点を箇条書きにするようにするだけなら、時間は５分もかかりません。
その５分の労力によって、マネージャーや他のメンバーが質問しに来る時間を無くしてチーム全体の生産性を高めてみんな早く帰れるようになると考えれば、業務中にtwitterやfacebookを眺める５分間を差し出すことは十分割に合うことだと思うのですが、どうでしょうか？ｗ
先ず隗より始めよということで、自分からチケットの書き方を変えてみると良いと思います。
別に文句を言う人はいないはずです（多分）
自分も１人で上記のようなことを勝手に始めましたが、段々他の人が真似するようになりました。
