Edited at

チケットの書き方

メンバーの一部がスムーズに情報共有できるチケットを書けず

苦戦しており、相談を受けた時に色々言った内容を

書き起こしたもの。

荒いけど誰かの参考になるかもしれないので共有。


2019/09/07 宣伝追記

技術書典サークル参加します。

チーム運営どう考えて何をやったかまとめた本とセキュリティの

入門書を頒布するので気になった方は是非。

https://techbookfest.org/event/tbf07/circle/5671044488626176


書いた人の環境

業務ツールとしてチャット、Redmine、Wikiを使用。


  • チャットで会話して相談・整理・調整する。

  • タスク、課題はチケット化して管理。

  • ナレッジはWikiに書いて共有。

業務内容はシステム開発と運用保守でソフトウェア開発ではない。

Redmineはタスク・課題管理に使用。

以下、メンバーに伝えたことを清書したもの。



 前提


  • チャットはフロー情報で消える。

  • チケットは決定した作業毎に切り、その事項に関して細かい情報や状況を書く。

  • Wikiは確定した情報や今後役に立ちそうなナレッジを残しておく。

チャットで決めて、作業をチケットにして、成果はWikiにまとめる

1チケット1成果になるように切る。

切った後に状況変わって必要作業(ゴール)が

増えたのなら、別に関連チケットとして切る or 相談して整理。


書き方の大原則

どんなチケットでも大原則として

「誰が、何を見て、どう考えて、何を決めて、何をして、どうなったか」

を明示的にする必要がある。

チケットなら記入者が自明なので場合によっては省略可。

ただし、理由の明記は必要。


例)

機器Aのログxxを見て、出力されてるyyがzzなのでエラーと判断した。


「決定した」「完了した」「解決した」など断定するときは

「何を見て、そうしたのか」理由も添付しないと本当か分からないので特に注意。

詳しい人が見たらその理由がそもそも間違ってることもある。


なぜ細かく書かなければならないのか。

「誰が、何を見て、どう考えて、何を決めて、何をして、どうなかったか」

を書くのは面倒くさいが理由はちゃんとある。


誰が

決定した人が分からないと内容の優先度や重要度が判断できない。

その調査、実装、解析方法を取ると決定した人は誰か。


何を見て、どう考えて

判断した理由が分からないと確実性が判断できない。

報告者の思考が分からないとアドバイスができない。

判断を誤った理由が分からないと訂正ができない。


何を決めて、何をして

今までの情報をふまえて、どう決めて何をしたか。

それが分からないと作業を始めた状態と、今の状態、

どこに向かおうとしてるのか判断できない。


どうなったか

今どんな状態になったか分からないと、

作業完了までに何が必要か分からない。

どの形式もこの形が大原則。それを踏まえた上で書き方は次の三種類

1. 自分用のメモ

2. 引き継ぎ用の状況整理

3. 責任者(担当者)を変更してアクションを促すもの


書き方の種類は3種類


1. 自分用のメモ

自分が見やすい範囲で好きに貼ってOK。

最後にWikiなり資料なり手順書なりにまとめる際に必要ななりそう情報やログ、

現状把握や問題の整理、考え等を忘れないように書いておく。

形式こだわらず好き勝手に自由に書いていいが、

その作業の内容を忘れた自分が読んで思い出す助けになるように書くこと。

自分が読んで分からないは意味がない。


2. 引き継ぎ用の状況整理

「そのチケットでやるべき作業がどんな状態か」分かるようになっていること。


  • 残りのやるべきこと

  • その作業の理由

理由は無くても残作業が明確なら作業はできるが、

理由が分かれば楽するために考えることができる。


「xxxするスクリプトを書く」


ではなく


AのデータをBのために定期的にまとめる必要がある。

データの取得はすでにスクリプトαで行っているがまとめるために整形する必要がある。

Aのデータ量が増加しており手動での実施に時間を要している。

今後も増加が予想されることから稼働削減のため整形スクリプトを書く。


なら、スクリプト書いてと渡された人が

別にスクリプト書かなくてもあれでやれない?

とか考えられる。


やるべきこと

分かりやすく簡潔に書く。


例)

Aのデータを整形するスクリプトを書く。



作業の理由

書くべきは以下の点


  • 前提、背景、経緯など


    • 前提を共有されていないと判断を誤る

    • 背景が分からないと理想の状態(ゴール)がどんなものになるか考えられない

    • 経緯が分からないと、これからどうゴールに行けば良いか判断できない。



  • 今どんな状態か


    • 実施者が何を、どうしようとして、どこまで進んだか?

    • 分かっている問題は?

    • 既存の問題をどうしたいのか?



  • 何が残っているのか


    • 問題があって進まないなら「何を」「なぜ」「どのような手段で」解決しようとしているのか

    • やれてない作業は何か

    • 注意点は何か




例)

(前提・背景・経緯など)

データAをBのために定期的にまとめる必要があるが、

データ量増加に伴い手作業でやってた整形を自動化したい。

取得はスクリプトαで実現済みのため整形部分を追加で作る

(今の状態、何が残ってるか)

Python3.7を使用し作成することでxxxさんと調整済みで

作成のために使用するxxxにPythonのインストールまでは完了。 (今の状態

処理フローを検討中の状態。(残り作業


と書けば


データAを整形するスクリプトよろしく。チケットxxx番


と共有するだけで必要な情報は伝わる。

また場合によってはスクリプトを作るのが最適解なのか考えて

投げられた人が別の楽な方法を提案できるかもしれない。


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は本当にそうなのか?

公式ドキュメントで見たからそうなのか

今までの作業経験からの勘なのか、

誰か詳しい人が言っていたからそうなのか。

事実か否かは厳密に分けて書くこと。

たとえ判断が間違ってても原則を守って書かれた情報なら役に立つが、

事実と憶測がごちゃまぜになった文章は毒になるので要注意。


2019/09/16追記


無い情報より残ってるクソ情報

「全然まとまってないクソみたいなチケット更新するな」でない ので、もし、これを読んでチケット更新やドキュメント化のハードルが高いと思ってしまった人が居たらごめんなさい。

まとまった情報>>とりあえずでも残した情報>>>>越えられない壁>>>>残さない

情報は残すだけで価値があるので残さないより、ログだけ、主観オンリーでも無いより遥かにマシ。

ただ、まとまっていないと整理する手間を読み手の方が負うので場合によっては

「アイツに任せると余計に手間が掛かる。教える時間もないしやったほうが早い」

が発生する。

ただ、なにかあった時はそれを追える。

それすら無いとまず追うものを探すところから始めるのでとてもコストが高い。

まずは残す。まとまってなくても残す。なんでも良いから残す。

とにかく残す。


「教えてもらえる」スタート地点に立てる

情報がまとまっていなくても、教えられる時間があれば読み手や報告を受けた方が時間を割いて対応できるけど、必ずしもそうではない。

でも、教えないといつまで経っても戦力にならないので双方つらい。

少ない時間で効率よくピンポイントで教えてもらうために「何を見て、どう考えて、何を決めて、何をして、どうなったか」をきちんと説明する必要がある。

何を見たか分からない。

何を考えてるか分からない。

何をしたか分からない。

何に困っているか分からない。

この状態からスタートではコストがとんでもなく高い。

間違っていても自分が進んで来た道と行きたい箇所と、今どこにいるかが

分かっていれば話は早い。

何を見たかわかれば、誤った見方や調査方法を正せる。

何を考えたかわかれば、誤った理由・知識・足りなかった前提を教えられる。

何をしたかわかれば、誤った方法やより効率的な方法を教えられる。

たとえ誤っていたとしても、きちんと正確に情報整理できていれば教えてもらえるスタートラインに立つことができる。

すべてを一度に教えてもらえなくても、ちょっとずつでも教えてもらえるようになる。

円滑な情報共有は相手の為ではなく自身のためになります。