はじめに

この文書は, 最低限伝わるのチケットの書き方を, 同僚に身に着けてもらうことを目的にしています. その方法は, 読者が容易に理解できる文書を書くように心がけ, 振り返って改善を継続することです.

チケットはチームの資産です. 常に自分が作成したチケットについて, 内容が読者に理解しやすかったかを振り返り, 次の機会に改善することが重要です. 初めから完璧な文書を作成できる人などいないですし, 誰が書いた文書も常に足りていません. 伝わる文書, 伝わった文書, 伝わったからいいやの文書, それぞれ異なります.

他人が作成した, 理解が難しいチケットを修正してはいけない, という法はありません. より上手くチームが動けるように改善すべきです. 自分が作成したチケットが修正されたなら, それは学ぶ機会に恵まれたということです.

チケットは, タスク管理システムやイシュー管理システムにおける, 一つのタスクやイシューを管理するための一連の情報を言います. チケットの概念の名称はシステムによって異なるため, 読み替えてください.

チケットの文書

チケットの文書は読者に内容を理解してもらうためのものです. 自分のToDo用のチケットというものがあるかもしれません. それをチームのシステム上に作成する理由は, 他人が読むことを前提としているはずです. 本当に私的ToDoなら, 自分でシステムを立て, そこに書くべきです. チームの場と私の場を混同してはいけません.

内容

チケットの文書では, ひとつの主題に集中します. そして, ひとつの主題について, 事実や状況といった情報と意見を正確にもれなく簡潔に記述します. 感想などの心情的要素を書きません.
情報の内容は, 主題（文書の目的）と読者の要求によって変わりますが, 意見との区別を明確にします.
事実は, あいまいな表現や主観に依存する形容詞を使わず, できるだけ明確に記述します.
意見は, 事実の上に立ち, 論理的に導き出した結果です. 意見の記述は複数の評価が並立しますが,
読者が記述された事実から評価できる必要があります.

事実と状況

事実と実際に起きた状況だけを正確に記述します. 意見とは言えない, 論理的理由のない憶測は無視されるため書かない方がいいです. 結果的にその憶測が当たったとしても偶然です, タスクの担当者は参考にしていません.

私がよく見る憶測の文章は, 次のようなものです. 憶測に時間を費やす必要はありません, あなたの仕事に時間を使ってください.

× おそらく, 〇〇〇が原因な気がする

曖昧な表現

■ おそらく, たぶん, らしい, かもしれない, と思う

事実かどうか確認してから書くようにします.

タスクでは手順を追加することになります. 手順の粒度が大きい場合, 別タスクになることもあります.

たぶん, 〇〇〇の方が有効だと思います. △△△という方法で確認してみます.

イシューでは再現できなかった, 再現のために試行する時間がないこともあると思います. その場合はそのまま書けばいいです.

〇〇〇という手順で, 3/10で再現しました
〇〇〇を試しましたが, 再現できませんでした
再現するかは試していません

会話では, 次のように曖昧な表現を使ってしまった時に修正します.

たぶん, 〇〇〇だと思います. 少し待ってください, 確認します.

■ 擬音語, 擬態語

その意味や度合いは個人の心情に依存します, 絶対に使わないようにします.

× バーンと表示してほしい
× ビャーと出てくる
× ドーンって感じで

言葉の選択

誰でも理解できる言葉を選択します. 一般的にチーム人員は変わるものです. 未来の見知らぬチームメンバが理解できるように書けばいいです. 指しているものが変わる可能性がある言葉, あれ, それ, は絶対に使わないようにします. バージョンを表す, 最新版, 最新の, も使ってはいけません.
余談ですが, 聞き手が理解できないことを解った上で, 特定コミュニティだけで通じる言葉を使う同僚がいます.

簡潔な文書

英国首相であった, ウィンストン・レナード・スペンサー・チャーチルは ([1],[2],[4]),

われわれの職務を遂行するには大量の書類を読まねばならぬ。その書類のほとんど全てが長すぎる。時間が無駄だし、要点をみつけるのに手間がかかる。同僚諸兄とその部下の方々に、報告書をもっと短くするようにご配意願いたい。

という書簡を部下に送ったそうです. 読解に時間がかかる文書は, 他人に時間を浪費させています.

特に過度な敬語は無駄です. もし, チケットに過度な敬語を使う必要があるならば, チームビルドに失敗しています. チームメンバの関係を修復すべきです.

チケットの書き方

共通

会話をしない

会話は口頭やチャットツールで行います. その会話の中で決まったこと, 補足すべき事項をチケットにまとめます. チャットツールは記録する目的には向いていません. 会話のやりとりで, 相手が理解した・確認が取れた, と思い込んではいけません.
チケットはチームで解決することについて書きます. 誰か特定の人にお願いするのではなく, 全員で解決するものです.

× タイトル:〇〇〇をお願いします

タスク

次の4つを書くといいです, 全てを書く必要はありません.

目的
- どうしてそれを行うのか
- 次の手段を検討・再考することにつながる, 重要な項目です
  - 副次目的があれば, 優先順位をつけて, 書いておくといいです
  - 機能を削らなければときの判断材料です
手段・手順
- 目的を実現する手順です
- 機能を削る場合に変更されます
目標
- 目的が達成されたかどうか判定するための材料です
- 数値で表現できる方がいいですが, 主観に依存することも多いです
- 具体的成果物でもいいです. できれば成果物の品質も数値で表現できるほうがいいです
完了条件
- 目標に到達したかどうかが基本ですので, 目標と混ぜて記述してもいいです
- 完了条件と目標がずれていた場合, 目的の設定がおかしい可能性が高いです

バグ

状況
- いつ, どこで, 何をしたか
  - ソフトウェアにおいては, これは一体なことが多いです
  - ゲームなどの場合, 何をしたかと不具合発生のタイミングが対応しない場合があります
  - 真に正確であることではなく, 観測された事実であることが大事です

〇〇〇画面で, △△△したときに
〇〇〇画面で, △△△していたときに

期待される状態
- 仕様で決めた状態
- 一般的に望ましいと思われる状態
  - 仕様の不具合を含めて見直しをする必要があります
再現手順
- あればいいが, 再現するために過度な時間を費やす必要はないです
- 憶測を書いてはいけません

参考に, エンジニアの手順を示します.

再現して, 確かに起きることを確認します
- 100%再現できる状態を探します. プログラムの原理的にこれは必ず存在します
  - ハードウェアや宇宙線によるビット破壊は考慮しません
  - 外部モジュールが原因の場合は, 全く別の解決方法になります
不具合が発生した瞬間に実行されていたプログラム片を特定します
- そこで実行されていた命令か, 使用していたデータのどちらか, または両方に原因があります
原因を特定して修正します
1.で特定した再現手順で不具合が起きないことを確認します
- 原因によって, 影響がある範囲も不具合が起きないことを確認します
- ログやアサーションなど, 同じ不具合が起きた場合に検出できる仕組みを導入します

まとめ

あなたの読者が内容を理解できるか? それだけです. そのために改善を継続します.

最初から誰に対しても厳格にする必要はありません, より良い状態に改善していけばいいだけです.

〇〇〇画面がおかしい

というタイトルのチケットを回されたら, エンジニアが修正すればいいだけです.
時にはチケット上で会話することもあるでしょう. 方法に縛られる必要はありません.

正しく動作することを確認しました. 修正ありがとうございます. クローズします.

参考文献

[1] 木下是雄,「理科系の作文技術」,1981
[2] 木下是雄,久間月慧太郎,「まんがでわかる　理科系の作文技術」,2018
[3] Barbara Minto,山崎康司,「新版考える技術・書く技術」,1999
[4] https://studying.jp/engineer/blog/20191226.html