「伝わるチケット」の書き方

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

「伝わるチケット」の書き方

「伝わるチケット」の書き方

onozaty

More Decks by onozaty

Other Decks in Technology

Featured

Transcript