チケットに書いてあることがさっぱりわからないことがある。情報を伝えるために書いたのに、相手に理解されなければ無駄になってしまう。また、書いてある文章を理解するために、書いた本人に直接聞くこともある。それなら書いて残すコストが無駄になっていまう。そのようなことがないよう、人に伝わるチケットの書き方を整理してみた。
チケットを書く心がまえ
事実と意見を分けて書く
事実と意見を混在して書くと、事実がねじ曲がってしまう。事実とは何でしょうか？ 意見とは何でしょうか？
- 事実＝客観的
- 意見＝主観的
事実とは客観的な事象や言動などを指し、意見とは主観的な考えや評価などを指す。もし客観的な言動が事実として書かず個人の意見として書いては誤解を与える。また主観的な考えを意見として書かず全体の言動として書いてもやはり誤解を与える。
次の例文を見てみよう。
問い合わせに対して回答が済んでおり、課題としては完了とするのが妥当であるため、その旨をメンバーに周知してチケットをクローズした。
「完了とするのが妥当であるため」と書いているので、「完了が妥当」と判断するのが当然のように読みとれる。この「完了が妥当」の判断基準は何だろうか？ 記載した本人にとっては妥当な判断かもしれないが、多くの人にとってはそうでないかもしれない。事実でないことを事実かのように書いてしまうと、その記載箇所を誰も評価せずにチケットのステータスが進んでしまうことがある。あとになって「なんでこの内容でクローズしたのだろう？」と混乱してしまうことがある。
次の例文を見てみよう。
問い合わせに対して回答が済んでおり、課題としては完了とするのが妥当と考えたため、その旨をメンバーに周知してチケットをクローズした。
この記載であれば「完了が妥当」の判断が個人的な意見であることが伝わる。個人的な意見であることがわかればこのチケットを見た管理者などが「第三者から見ても完了にしてよいか」判断する機会を持つことができる。あとになって見ても「主観的な判断で完了と考えた」ことが理解できる。
事実と意見を区別するためには語尾を明確に分けることだ。以下の例を参考に区別しよう。
- 事実：「～である」
- 意見：「～と考える」、「～と推測する」、「～と判断する」、「～かもしれない」、「～したい」
原因と結果を分けて書く
原因と結果をごちゃまぜにしてしまうと、何が起きたのか、何が問題なのかがわかりづらくなってしまう。
次の例文を見てみよう。
接続数が多いため、DBコネクションをクローズしていないとエラーが発生する。
この記載内容を見ると、原因は「接続数が多い」ことにあるように読み取れる。エラーを回避する方法は接続数を少なくすることだろうか？
実際のエラーの原因はDBコネクションをクローズしていないことだ。クローズしていないから、接続数が多い場合にエラーが発生するのだ。もしエラーを発生しないようにするためには、DBコネクションをクローズすればいいのだ。
次の例文を見てみよう。
DBコネクションをクローズしていないため、接続数が多い場合にエラーが発生する。
この記載であれば、原因と結果が正しく伝わる。
問題点を明確にする
起票者は問題点が何かを明確に書かなければならない。問題点は起票者以外の人にも伝わるように書こう。
次の例を見てみよう。
ユーザ登録画面でふりがなを未入力のまま登録ボタンを押したがユーザ登録内容確認画面に遷移した。
起票者は「入力項目が未入力の場合は、ユーザ登録画面を再表示する」ということを知っているため、上記の説明で何が問題なのか明確だと思っている。しかし、画面仕様を知らない第三者が見たら、どこが問題なのかわからない。問題を明確にする場合は、期待する正しい結果と実際の結果を両方明記することだ。
ユーザ登録画面でふりがなを未入力のまま登録ボタンを押したがユーザ登録内容確認画面に遷移した。本来であればユーザ登録画面を再表示すべきである。
このように書くことで何が問題なのか第三者にも伝わる内容にすることができる。
次の例を見てみよう。
画面設計書の記入例覧に「帳票出力する文字の桁数を明記する」と書かれている。
この例もどこが問題なのかがわかりづらい。わかる人にはわかる書き方になっているが、新しくチームに参画したメンバーには伝わらないかもしれない。
画面設計書の記入例覧に「帳票出力する文字の桁数を明記する」と書かれている。正しくは「画面表示する文字の桁数を明記する」である。
このように書けば、修正箇所が明確だ。
時系列を正確に書く
順番に誤りがあると全く意味が異ることがある。
次の例を見てみよう。
ユーザにレビューしてもらい、「テーブル設計書」と「レビュー記録票」を修正した。
実際のプロジェクトで、このような記載を見たことがあった。これを読んだ時の私の理解は「レビューで『テーブル設計書』に対する指摘があった。その指摘を『テーブル設計書』に反映し、また『レビュー記録票』を記載した」というものであった。
しかし、「レビュー記録票」を開いてみたところ「指摘なし」とだけ書かれていた。確認をしたところ、実際には指摘はなかったとのことだった。
本人に聞いたところ、本来であれば、次のような書き方が適切だったようだ。
修正した「テーブル設計書」をユーザにレビューしてもらい、結果を「レビュー記録票」に記載した。
時系列に整理すると
- 「テーブル設計書」を修正した。
- ユーザにレビューしてもらった。指摘はなかった。
- 「レビュー記録票」を記載した。
ということだ。最初の記載内容と実際の内容がまったく異なってしまっている。
時制（過去・現在・未来）を明確にする
作業内容を書くとき、すでに終わったことなのか、これからやる予定なのか、あるいはやっている最中なのか、明確にしよう。
次の例を見てみよう。
設計書を修正
このように書かれたらどのように理解できるだろうか。
- これから修正する？
- 現在、修正中？
- すでに修正済み？
これらは全て異なるステータスを意味している。「これから修正する（＝未対応）」と「すでに修正済み（＝完了）」では、意味が全く違う。だから時制は明確にしなければならない。
設計書を修正した
このように書けば、作業が完了していることがはっきりと伝わる。
何をしてほしいのかはっきり書く
この文章は読み手に何を期待しているのだろうと感じるものがある。
次の例を見てみよう。
現行システムを開発したベンダから過去の設計書を受け取りました。○○フォルダに置いておきますので、よろしくお願いいたします。
このような文章だと2通りの読み方ができる。
1つは、受け取った設計書をしっかり読んでください、という読み方。実際、このように読みとって数百ページの設計書を読み、あとで「別に見なくても良かったんですよ。アハハハ」と笑われたことがある。「だったらそう書けよ」と怒りを覚えたことを今でも記憶している。
もう1つは、○○フォルダに置いておくので必要なときに見てください、という読み方。置き場所の周知という理解だ。
どちらにしても「よろしくお願いいたします」だけでは意図が理解できない。相手にどうしてほしいのか、あるいは何もしなくてよいのか、はっきり書かないと、相手に誤った行動をさせてしまう。
誰にわかるように書けばよいか
チケットの内容をどれくらい詳細に書けばよいか判断に悩むことがある。新しくチームに参画したメンバーでも分かるように書くと、背景・経緯に始まり、用語の説明を含めてかなり詳細に書かなければならなくなる。一方、チームで長く仕事しているメンバーが分かるように書くとすると、簡単な内容で済むことがある。
どのレベルに合わせるかはプロジェクトやチームの特性に合わせて定めればよい。もし、基準がなければ「習熟度がチーム全体の中間に位置する人に伝わる」ことを基準としてみよう。習熟度が低いメンバーにはわかりづらい内容となってしまうが、そのようなメンバーには作業前の説明や作業後のチェックなどを必ず行うばずだ。そのときにチケットに書かれていない情報を補足してあげればよい。
チケットの具体的な書き方
概要・タイトルの書き方
問題の全容がわかるように書く
概要・タイトルは、問題の全容を端的に表現できることが望ましい。概要・タイトルを読むことで内容を把握できることが望ましい。ただし、実際には文字数の制約から難しいことがある。
識別できるように書く
概要・タイトルは、どのような問題なのかを瞬時に分かるように書くことが望ましい。一覧表示された場合に、どれがどの問題を扱っているチケットなのかが分かることが重要だ。似た概要・タイトルにしてしまうと、チケットを探しにくくなってしまう。
起票時の記載内容
起票時には、事象を正確に記載することが重要だ。起票者の推測や判断などよりも、何をしたら、何が起こったを、客観的に、再現可能な内容で、正しく人に伝えることだ。事象の原因や、問題の重要度などはなくてもかまわない。
完了基準を明確にする
チケット起票時に完了基準を明確にしておこう。何が済んだらそのチケットを完了するのかが明確でないと、いつまでも「ステータス＝完了」にならず、「ステータス＝対応中」のままになってしまうことがあるからだ。
例えば、他チームが作っているドキュメントに誤記を見つけた場合、完了基準として「ドキュメントの修正が終わる」ことにしてしまうと、ドキュメント修正に時間がかかってしまうとなかなか「ステータス＝完了」にならない。また、他チームなので状況を逐一確認できない場合であれば、ますます「ステータス＝完了」にならなくなってしまう。
一方、完了基準として「誤記の内容を他チームに連携する」ことにしておけば、通知後、すみやかに「ステータス＝完了」にすることができる。
自分たちの力のおよばない作業が終わることを待ち、チケットが完了にできないと、いつまでたっても「ステータス＝対応中」のままになってしまう。そうすると進捗が進んでいないように見えてしまうから要注意だ。
重要度の判断をする
起票された問題の重要度を判断しよう。重要度を決める基準としては以下のようなものがある。
- 損失の大きさ
- 悪い状態になる時間
- 悪い影響を被る人
- 悪い影響が発生する頻度
アサイン時の記載内容
担当者に作業を振る場合は、作業内容が明確でなければならない。また、ゴールが明確できなければならない。分析までなのか、修正までするのか、テスト結果報告までするのか、明確に指示しよう。
対応時の記載内容
担当した問題の対応を行ったら、対応内容について記載しよう。記載する内容としては以下のようなものがある。
- 問題の原因
- 対応内容
- 対応途中であれば状況
- ステータス
- 対応日時
- 対応反映対象資材やバージョン
確認時の記載内容
担当者が対応を終えたらその内容について確認しよう。確認した結果は、相手に伝わるように記載しょう。記載内容としては以下のようなものがある。
- 確認結果
- 問題があれば指摘内容
- 問題がある場合の再現方法 チケットの分類（故障・機能改善・機能追加・調査依頼など）
文章の書き方
一文を短く書く
文章を書くとき、一文を長く書いてしまうと、わかりづらい文章になることがある。
次の例文を見てみよう。
このバグはDBコネクションのプール数が適切数でないことはもちろん、そのためにアプリケーションで例外が発生し、結果、システムが停止してしまう事態となった。
この例文のように、読点（「、」）で文をつなげてしまうと、複数の内容が盛り込まれてしまい一文が長くなる。一文が長いとどこが重要なのかわかりづらくなってしまう。その結果、読み手にとってわかりづらい文章となってしまう。
次の例文を見てみよう。
このバグはデータベースコネクションのプール数が適切でない。そのためアプリケーションで例外が発生してしまった。結果、システムが停止してしまう事態となった。
この例文のように、句点（「。」）で文章を区切るようにすると、文章が理解しやすくなる。理解しやすくなることで、誤解を与えたり、伝え漏れを防ぐことができるようになる。
箇条書きで記載する
文面の中に多くの情報を盛り込むとわかりづらい文章になることがある。その場合は箇条書きを使うと読みやすく伝わる文章にすることができる。
次の例を見てみよう。
バグを確認するためには以下の通りの操作を行う。まずログイン画面でログインとパスワードを入力しログインボタンをクリックすると「商品一覧画面」が表示される。「商品一覧画面」に表示された商品一覧のいずれかの商品IDをクリックすると「商品詳細画面」が表示される。「商品詳細画面」の戻るボタンの位置が右寄せとなっていることが確認できる。
これだと文がごちゃごちゃしてよくわからなくなってしまう。
次に箇条書きで記載した例を見てみよう。
バグを確認するためには以下の通りの操作を行う。
・ログイン画面でログインとパスワードを入力しログインボタンをクリックする。
・「商品一覧画面」が表示される。
・「商品一覧画面」に表示された商品一覧のいずれかの商品IDをクリックする。
・「商品詳細画面」が表示される。以上の操作により、「商品詳細画面」の戻るボタンの位置が右寄せとなっていることが確認できる。
これでわかりやすくスッキリとした文章になった。
敬語や修飾語を省く
敬語があるとわかりづらい文章になることがある。敬語があることで文章量が増え、読むべき箇所が特定できなくなってしまうからだ。また敬語の「～られる」と受動態の「～られる」がどちらの意味なのか判別つかなくなることがある。
また修飾語が文章を読みづらくすることもある。文章量が増えたり、文章を難しくしてしまったりするからだ。「とても」「できるだけ」など、言葉がなくても文章の意味が変わらなければ省くようにしよう。
参考書籍
小笠原信之『伝わる! 文章力が身につく本』（高橋書店）
成清弘和『理系のための論理が伝わる文章術』（講談社）
阿部紘久『文章力の基本』（日本実業出版社）
高橋慈子『90分で学べるSEの文書技術』（日経BP社）
菅野裕ほか『Trac入門』（技術評論社）