第18回redmine.tokyo勉強会にて発表した『「伝わるチケット」の書き方』のスライドです。

1. 「伝わるチケット」の書き方
2020-05-23
第18回redmine.tokyo勉強会
@onozaty

2. 自己紹介
• Hirokazu Onozato
• 株式会社ユニスティ所属
• ソフトウエア開発者
• Redmine歴11年くらい
• View customizeプラグイン作者
• https://github.com/onozaty/redmine-view-customize
@onozaty
https://github.com/onozaty

3. 本日のお題
「伝わるチケット」の重要性と
書き方のポイントについて
リモートワークが進み
対面でのコミニケーションが
取りずらい今だからこそ

4. 「伝わるチケット」の重要性
• チケットは起票したら終わりではなく、そのチケットを確認する人
がいる。
• 起票者1名に対して、確認者が複数名という場合も多い。
起票時間 ＜ 確認時間

5. 「伝わるチケット」の重要性
• 確認するのにかかる時間を減らすことが重要。
• 起票者が「伝わるチケット」を書くことによって、確認にかかる時
間を減らしたい。
チームの生産性向上へ

6. 個人の時間とチームの時間
チケットに限らず、チームで作業しているならば、常に個人(自分)の
時間とチーム(自分以外)の時間の両方を考えるべき。
【開発現場での例】
コーディングがとても速い人がいても、それを読む人(メンテナンスする他の人)にとって理解に
時間がかかるコードならば、結果的にチーム全体としての生産性を下げることになりかねない。
コーディングする人が少し時間取ってコードを見直すだけでも、見直しにかけた時間以上に他
のメンバの理解に要する時間を削減でき、チーム全体の生産性を上げることができる。
他の人の作業時間を減らすために、
自分に何ができるか常に考えていく

7. 「伝わるチケット」の定義
1. 必要な情報が揃っている
2. より短い時間で理解できる

8. 必要な情報が揃っている
必要な情報が揃っていないと、その情報にたどり着くために余計な時
間が発生する。
• 追加情報をチケット起票者に聞く
• 自分自身で調べる
その情報に一番近いのは起票者のことが多いので、起票者がチケット
に書いていれば、もっと短い時間で済ませられることが多い。
必要な情報＝チケットの確認者が欲しい情報

9. 必要な情報が揃っている
• 必要な情報はプロジェクト毎に異なるので、Redmine運用開始時点
で考えるのは難しい。
• Redmineを運用していくと、このトラッカーならばこの情報が必要
といったことが見えてくるので、チーム内で相談しながら、必要な
情報として定義、追加していく。
チケット起票時に必要な情報を
入力することをチームの目標に

10. 必要な情報の入力を手助けするもの
必要な情報の入力漏れを防ぐため、入力の手助けをするようなものを
利用する。
• カスタムフィールド
• Redmine Issue Templates plugin

11. カスタムフィールド
カスタムフィールド(Redmineの標準機能)を使って、必要な情報を入
力項目として追加できる。
• 様々な入力形式に対応
• あらかじめ選択肢が決まっているものについては、
リストとして定義することで入力時の選択が楽に
• テキストや数字などでは、正規表現で入力制限を
つけることによって、入力誤りを防げる
• 必須/任意の指定や、トラッカーに応じた表示/非表示の制御も可
能
• フィールド単位での検索もできる

12. Redmine Issue Templates plugin
Issue Templatesというプラグインを利用することで、チケットのテン
プレートが作れるので、テンプレートとして必要な情報の入力欄を用
意することができる。
• https://github.com/akiko-pusu/redmine_issue_templates
• チケット作成時のデフォルトテンプレートもトラッカー毎に指定す
ることができて便利。
• 説明欄だけでなくフィールドにも
値を設定することができる。
@akiko_pusu

13. カスタムフィールドとIssue Templatesの使い分け
それぞれ得意なところがあるので、うまく使い分けると良い。
• 選択肢やフォーマットが決まっているようなもの
→カスタムフィールド
• 入力の手間や間違えをなくせるのと、後からフィールドごとに検索できるのも大きな
メリット
• 文章や画像として入力したいもの
→Issue Templates
• 自由度が高い
• カスタムフィールドでも長いテキストという形式があるが、複数並べるとかなり場所
を取るのでしんどい

14. カスタムフィールドとIssue Templatesの使い分け
どっちにすればよいか迷う場合には、Issue Templatesで定義しておく
のがおススメ。
• カスタムフィールドで定義するより、Issue Templatesで定義する
方が手軽で時間もかからない
• カスタムフィールドにしようとするために、事前に項目の定義に時間をか
けるのはもったいない
• カスタムフィールド追加にはシステム管理者権限が必要
• Issue Templatesで定義しておいて、規則性が見えてきたらカスタ
ムフィールドにすればよい

15. 「伝わるチケット」の定義
1. 必要な情報が揃っている
2. より短い時間で理解できる

16. より短い時間で理解できる
より短い時間で理解できるものにするためには、情報がわかりやすい
形で書かれている必要がある。
情報に適した表現方法を使うことで
よりわかりやすく

17. チケット上での表現方法
チケット上での表現方法はいくつかあるので、それをうまく使うこと
で、より分かりやすい形で表現することができる。
• 文章
• 画像
• アニメーションGIF
• 添付ファイルなど
ついついなんでも文章で表現しようとしがちなので、他の方法も適宜
使い分けていくのが良い。

18. 画像
下記のような場合は、積極的に画像を使った方が良い。
• UI上(例えばブラウザ上)で発生した現象を説明する場合
• 色や形など、目に見えるものを表現する場合
画像の方が確認者に伝わりやすく、起票する側としても文章で表現す
るより簡単なはず。

19. 画像
Redmineでは下記の2パターンで画像を添付できる。
• 画像ファイルとして保存済みのものを添付
• クリップボードにあるものを画像として添付
(Redmine 4.1 以降、またはプラグインが必要)
添付するだけではなく、インライン画像(!画像ファイル名!)として説明
欄で見える状態にしてあげるのが良い。

20. clipboard_image_paste プラグイン
clipboard_image_paste プラグインを利用すると、クリップボードから
添付する際に範囲を調整でき、とても便利。
• https://github.com/peclik/clipboard_image_paste
本家サイトで提供されているものはRedmine4
への対応が行われておらず、Redmine4以降で
利用するには下記のような他の人がforkして修
正しているものを利用する必要あり。
https://github.com/Utopism/clipboard_image_paste

21. アニメーションGIF
• 画面の動きを説明するようなものは、画像ではなくアニメーション
GIFにしてあげるとさらに良い。
• 特に操作手順が複雑なものは、
文章や細切れの画像だと伝わり
ずらいので、アニメーションGIF
にする効果が高い。

22. アニメーションGIF
画面操作を記録してアニメーションGIFに変換できるツールがあるの
で、それを使ってアニメーションGIFを作成し、インライン画像とし
て添付する。
無償のツールで簡単にできる。
• ScreenToGIF (Windowsのみ)
• https://www.screentogif.com/
• LICEcap (Windows/Mac)
• https://www.cockos.com/licecap/

23. 添付ファイル
他の方法で表現するのが難しいときには、添付ファイルも使うと良い。
• ログファイルのように、ファイルとして既に存在し、説明欄で書
ききれないもの
• 重要と考える個所のみ抜き出して説明欄に記載しておき、全体もファイル
として添付しておけば、後から前後を確認したい場合に再度ログを収集し
なくて済むので良い
• Excelのような他のファイル形式で見た方がわかりやすいもの
• Redmineでも表をかけるが、フィルタやソートができないので、 Excelで
見た方が見やすいものは、 Excelとして添付されていた方が良い

24. 最後に
「伝わるチケット」を書くためのポイントを説明したが、一番重要な
のは
自分が他のメンバの立場だったら、
• どこがわかりずらいか
• 何を疑問に思いそうか
といったところ考えていくと、自然と「伝わるチケット」になってい
くはず。
チームの他のメンバのことを考えること