チケットの書き方（情報共有のための文書の書き方）
Qiitaに一度書いた内容ですがアカウント削除とともに消えた内容です。
Redmine絡みのイベントで書いた記事だったはず。
手元のメモから出てきたのでこちらに記載。
背景
メンバーの一部がスムーズに情報共有できるチケットが書けず苦戦しており、
相談を受けた時に色々言った内容を書き起こしたもの。
チケットというより、情報共有のための文章の書き方が正しいかも。
前提
業務ツールとしてチャット、Redmine、Wikiを使用していた。
チーム内の連絡や相談はチャットがメイン。
- チャットで会話して相談・整理・調整する。
- タスク、課題はチケット化して管理。
- ナレッジはWikiに書いて共有。
業務内容はシステム開発と運用保守でソフトウェア開発ではない。
Redmineをタスク・課題管理に使用している環境で
以下のような考えを元に各ツールを使用し業務を行っていた。
・チャットは流れる情報（フロー情報）なので消える。
・チケットは決定した作業毎に切り細かい情報や状況を残しておくために使う。
・Wikiは確定した情報や今後役に立ちそうなナレッジをキレイに整理して残すために使う。
チャットで決めて、作業をチケットにして情報残して、成果はWikiにまとめる
1チケットで1つの結果になるように切る。（手順書作る、xxの環境作る etc.）
切った後に状況変わって必要な成果（ゴール）が増えたのなら、
別に関連チケットとして切る or 相談して整理。
大原則
どんなチケットでも大原則として
「誰が、何を見て、どう考えて、何を決めて、何をして、どうなったか」
を明示的にする必要がある。
チケットなら記入者が自明なので場合によっては「誰が」は省略可。
ただし、それ以外と決めた理由は明記は必要。
例）
機器Aのログxxを見て、出力されてるyyがzzなのでエラーと判断した。
「決定した」「完了した」「解決した」など断定するときは
「何を見て、そうしたのか」理由も添付しないと本当か分からないので特に注意。
詳しい人が見たらその理由がそもそも間違ってることもある。
証拠となるログは絶対に残す。
コマンドの結果でも良いし、見た画面のスクショでも良い。
どんだけショボいものでは判断した理由となるものが残っていればあとから再確認/検証ができる。
なぜそう書かなければならないのか
「誰が、何を見て、どう考えて、何を決めて、何をして、どうなかったか」
を書くのは面倒くさいが理由はちゃんとある。
誰が
決定した人が分からないと内容の優先度や重要度、確度が判断できない。
その調査、実装、解析方法を取ると決定した人は誰か。
何を見て、どう考えて
判断した理由が分からないと確実性が判断できない。
報告者の思考が分からないとアドバイスができない。
判断を誤った理由が分からないと訂正ができない。
何を決めて、何をして
今までの情報をふまえて、どう決めて何をしたか。
それが分からないと作業を始めた状態と、今の状態、
どこに向かおうとしてるのかゴールが判断できない。
始めた状態とゴールがわからないと、全体でどれぐらいの作業量になるか分からない。
どうなったか
今どんな状態になったか分からないと、
作業完了までに何が必要か、残りどれぐらいの作業量になるかが分からない。
どんなチケットでもこの形
「誰が、何を見て、どう考えて、何を決めて、何をして、どうなったか」
は絶対に必要な大原則。
書き方の種類は3種類
大原則を踏まえた上で、さらに書き方は次の三種類
1. 自分用のメモ
2. 引き継ぎ用の状況整理
3. 責任者（担当者）を変更してアクションを促すもの
1. 自分用のメモ
自分が見やすい範囲で好きに貼ってOK。
最後にWikiなり資料なり手順書なりにまとめる際に必要ななりそう情報やログ、
現状把握や問題の整理、考え等を忘れないように書いておく。
形式こだわらず、急ぎなら大原則すら守らず好き勝手に自由に書いていいが、
その作業の内容を忘れた自分が読んで思い出す助けになるように書くこと。
自分が読んで分からないは意味がない。
必要なら後からきちんとある程度整理して原則を守った情報を追記しておくこと。
2. 引き継ぎ用の状況整理
「そのチケットでやるべき作業がどんな状態か」分かるようになっていること。
- 残りのやるべきこと
- その作業の理由
理由は無くても残作業が明確なら作業はできる。
できるが、理由が分かれば楽するために考えることができる。
例）
「xxxするスクリプトを書く」
この書き方は忘れないための「1.自分用のメモ」にしかならない。
引き継ぎ用は以下のように書いてあると嬉しい。
例）
AのデータをBのために定期的にまとめる必要がある。
データの取得はすでにスクリプトCで行っているが、まとめのために整形する必要がある。
Aのデータ量が増加しており手動での実施に時間を要している。
今後も増加が予想されることから稼働削減のため整形スクリプトを書く。
引き継ぎ用として必要な内容は次の2つ。
やるべきこと
分かりやすく簡潔に書く。
Aのデータを整形するスクリプトを書く。
作業の理由
- 前提、背景、経緯など
- 前提を共有されていないと判断を誤る
- 背景が分からないと理想の状態（ゴール）がどんなものになるか考えられない
- 経緯が分からないと、これからどうゴールに行けば良いか判断できない。
- 今どんな状態か
- 実施者が何を、どうしようとして、どこまで進んだか？
- 分かっている問題は？
- 既存の問題をどうしたいのか？
- 何が残っているのか
- 書いた時点で「何を」「なぜ」「どのような手段で」解決しようとしているのか
- やれてない作業は何か
- 注意点は何か
(前提・背景・経緯など）
データAをBのために定期的にまとめる必要があるが、
データ量増加に伴い手作業でやってた整形を自動化したい。
取得はスクリプトCで実現済みのため整形部分を追加で作る
（今の状態、何が残ってるか）
Python3.7を使用し作成することでサーバーチームとFix済み。
作成のために使用するxxxにPythonのインストールまでは完了。 (今の状態
処理フローを以下のもので検討中。(残り作業
と書けば
データAを整形するスクリプトDの作成よろしく。詳細はチケットxxx番見て。
と共有するだけで必要な情報を伝えることができる。
この様に書いてあれば、気が利く人なら
別にスクリプト書かなくても今動いてる別のあれでやれない？
今あるスクリプトCに整形処理まで入れるじゃダメなの？
とかも考えられる。
3. 責任者を変えてアクションを促す
何をして、完了報告をどうすれば良いかが明確になっていなけれならない。
- やるべきこと
- 必要な情報
- 実施作業の手順や注意点
- 完了したらどうするか
やるべきこと
分かりやすく簡潔に書く。
例）
ADサーバーにアカウント追加3名分
必要な情報
作業実施に必要となる情報を明記
例)
以下3名分のアカウントをADサーバーxxxに追加する。
- ユーザA/hogehoge@mail.com/所属グループ Admin
- ユーザB/fugafuga@mail.com/所属グループ Operator
- ユーザC/hogefuga@mail.com/所属グループ Operator
必要な手順や注意点
手順書を提示。ないなら誤解を招かないよう記述する。
「何を（対象）」「どうして（作業）」「どうなるか（結果）」
例)
手順は Wikiのページxxx を参照。
xxxでxxxを実行してパラメータxxxならOK。
mm/ddのxx:xx～xx:xxで実施すること。問題発生時はAさんに要連絡。
完了したらどうするか
完了後の報告はどのようにすれば良いか。報告先は誰か？
作業完了として判断するために報告先が結果として欲しい情報は？
例)
完了後にコマンドxxxでパラメータyyyを確認しenableならOK
念のため結果ログを要共有。
忘れた自分は他人
「誰が、何を見て、どう考えて、何を決めて、何をして、どうなかったか」
がはっきりしてないと見た人が判断のために情報収集する手間が掛かる。
ちゃんと書けて伝えられれば一発で済むし、慣れれば書くほうが楽。
自分用のメモは好きに書いてOKだが、忘れるので他人と思って書いたほうが楽。
後でチケット見返す詳細を忘れた自分は他人。
自分用のメモもある程度書いたら、引き継ぎ用のつもりでまとめておくと
未来の自分を助ける事ができる。
事実、主観を明確に分ける
見た人の判断の助けになる情報は多いほうが良い。
ので「だろう」「だと思う」「多分こう」も書いて良い。
が、事実とごちゃまぜにしない。
例）
xxxというログが出たのでyyyが問題だ。
このyyyは本当にそうなのか？
公式ドキュメントで見たからそうなのか
今までの作業経験からの勘なのか、誰か詳しい人が言っていたからそうなのか。
事実か主観かは厳密に分けて書くこと。
たとえ判断が間違ってても原則を守って書かれた情報なら役に立つが、
事実と主観がごちゃまぜになった文章は判断を誤らせる毒になるので要注意。
例）
Redmineが停止していた。
これは主観だけ。
具体的にどういった状態を示して「停止」なのか。
自分用のメモならこの書き方でも良いが、他人に伝えるには足りない。
例）
Redmineにアクセスできなくなったとxxxから問い合わせあり。
xxxのログにはyyyが出ておりエラーとなっていた。
サーバーにPingは通り、ブラウザアクセスすると503となったことを確認。
これは事実だけ。
Pingが通らない、xxxのログ、ブラウザアクセスして503なってる状態が分かるものを証拠として上げてれば完璧。
例）
Redmineのログにxxxが出力されておりエラーと判断した。
サーバーにPingは通り、ブラウザアクセスすると503になった。
（ログを実際に記載）
コマンドxxxの実行結果がxxxとなりApacheのサービスが動いてることは
確認できたのでRedmineのサービスが停止していると判断した。
事実に主観と証拠を記載したパターン。
本当に止まっていたのはRedmineか？NW側では？Apacheが落ちただけでは？
と判断して証明できるログ付きで記載した。
事実を書けば後からでも再確認と検証ができる。
ログの見方が違って判断が誤っていても他の人が修正できる。
無い情報より残ってるクソ情報
もし、これを読んでチケット更新やドキュメント化のハードルが高いと
思ってしまった人が居たらごめんなさい。
「全然まとまってないクソみたいなチケット更新をするな」では無いです。
まとまった情報>>とりあえずでも残した情報>>>>越えられない壁>>>>残さない
情報は残すだけで価値があるので、とりあえずのメモ、ログだけ、
主観オンリーでも無いより遥かにマシ。
まずは残す。まとまってなくても残す。なんでも良いから残す。とにかく残す。
ただし事実と主観はきっちりと分けて誤解を招かないように書く。
「教えてもらえる」スタート地点に立てる
教えられる時間があれば読み手や報告を受けた方が時間を
割いて対応できるが、必ずしもそうではない。
でも、教えないといつまで経っても戦力にならないので双方つらい。
属人化はなるべく避けないといつか破綻する。
少ない時間で効率よくピンポイントで教えてもらうために
「何を見て、どう考えて、何を決めて、何をして、どうなったか」
をきちんと説明する必要がある。
何を見たか分からない。
何を考えてるか分からない。
何をしたか分からない。
何に困っているか分からない。
この状態からスタートではコストがとんでもなく高い。
何を見たか分かれば、誤った見方や調査方法を正せる。
何を考えたか分かれば、誤った理由・知識・足りなかった前提を教えられる。
何をしたか分かれば、誤った方法やより効率的な方法を教えられる。
事実を正確に分かりやすく（読みやすく）共有してもらえれば、
詳しい人がなんとかできるし教えることもできる。
きちんと共有できれば一度に全て教えてもらえなくても、
ちょっとずつでも教えてもらえるようになる。
円滑な情報共有は相手の為ではなく自身のためになる。
教えてもらったり判明した
「何が間違ったか」
「どうするべきだったか」
チケットに残せば他の人にも共有される。
読む方はどうするべきか
「誰が、何を見て、どう考えて、何を決めて、何をして、どうなったか」
をきちんと把握できるか、事実と主観を誤解なく切り分けられてるか確認する。
原則が守られてても、事実と主観が切り分けられてない、
証拠がないものは本当に妥当か書いた人に確認して確認する必要がある。
自戒も兼ねて
「自分が、何を見て、どう考えて、何を決めて、何をして、どうなったか」
を一番正確に説明できるのは他人ではなく実施者の自分。
技術に対する知識不足や実施作業の経験の有無は関係なく、
新人でも他の人の助けになる良いチケットは書ける。
逆にいうとベテランが書く内容が必ずしも役に立つとは限らない。
分からなければ立場関係なくきちんと確認する必要がある。
だから気兼ねなく分からないところは聞いて欲しいし、聞かれたら快く答えるべき。
技術や知識、経験は大事だが、まずは「自分が何をしたか」を
きちんと誤解なくスムーズに、人に共有できるようにならないといけない。
その上に技術とか知識とか経験を積み重ねないと無駄が大きい
以上が、苦戦したメンバーに伝えたものを簡単にまとめたもの。
誤字脱字あったらごめんなさい。
もとの文章は発作的に書き出したものなので、
うまくまとまってるか不安ですが誰かの役に立てば幸い。
この内容にプラス、文章を構造化して書く（いわゆるテクニカルライティング
とかもありますが長くなるので割愛。
自分の観測範囲だと読みやすい良いチケット（文章）書ける人は
仕事もできたり働いてて楽しい人が多い印象が強いです。
最後に宣伝
数年前の技書博、技術書典で出した技術？同人誌をBoothで販売してます。
-
理想のチームの作り方
マネジメントの知識体系というより
「よく分からん状態でリーダーやることになって、
開き直ってこう考えて実践してなんとかした。」
をまとめたものです。 -
大事なセキュリティの話をしよう
「セキュリティは技術や仕組みでなく文化」
ということを理解してもらいたくて書いた本です。
興味が出た方は購入して頂けると、私の小遣いとやる気なります（）
Discussion