作業記録を残す意義

こんにちは。

システム開発チームの山本です。

実山椒の季節がやってきました。枝と実を分ける作業は控え目に言って地獄のような作業でした。
イワシと実山椒の煮付けとぬる燗が一番美味しいと感じた食べ方です。麻婆豆腐に入れるなど、そのポテンシャルは計り知れません。
「アク抜き」をしたあとに冷凍庫で凍らせた状態で揉むとパキパキと枝と実を簡単に分ける事ができるハックをその後知りました。同じ悩みを抱えている方がいらっしゃれば是非試してみてください。

弊社では、いくつかの栄養改善サービスを提供しています。サービスを運用する中でCSあるいはお客様からお問い合わせを頂き、調査や障害解決の対応を行うことが増えてきました。
伴って最近は「作業記録をつける」ことを心がけるようになりました。これを行うと何が良いのか、良い効果をもたらすために記録する際に何を気をつけているのかについて紹介します。

作業記録のメリット

属人化を防げる

ある程度の規模になってくると、複数人のエンジニアでアプリケーションを作ることになります。
その後バグなどが発生した場合、該当箇所の実装者が対応するのが最も早いです。しかしこれを続けてしまうと実装者しか対応できない状態のままです。

作業記録を見ながら実装者以外のエンジニアが対応することで、該当機能について理解が深まり対応できるエンジニアが増えることに繋がります。

あとから反省できる

作業が完了してから自分が行ったことを振り返ると、改善の余地があることに気づくことができます。対応の緊急度が高かったりすると、正確さよりも対応の速さを優先し過ぎて時に誤っていたり、その場しのぎの対応を行うことがあります。

記録に残しておけば問題の恒久的な解決や、改善について対応者以外のメンバーを交えて熟考することができます。

集計して障害対応頻度などを把握できる

ユカシカドでは、対応記録は github の issue に記録しています。この記録を bigquery などに同期することで「期間あたりの対応件数」「作業記録の対応者割合」などから、１人のエンジニアばかりが作業していないか、今月は作業が多く本来取り組みたいことに取り組めていないかなどを把握することが可能になります。

作業を記録するために気をつけていること

作業を行う理由を必ず書く

記録を取る際は対応をしながらなのでどうしても手短に済ませてしまいたくなり、行った作業だけを記載しがちです。そのような記録を見たひとは「なぜこの作業が適切と判断したのか」がわかりません。

作業記録には最初に必ず「事実」があり、「その事実から記録者が何を考えどのような理由で作業を行うのか、その作業で得られた結果（事実）から何を考えどのような理由で次の作業を行うのか。」を繰り返し記載すると他の人が見返した時納得してもらえると思います。

記録から対応を行う場合、理由まで書いておくことで「この場合は過去のケースと異なるので対応を変える」という判断もできるはずです。

実施したコマンドを順にすべて記載する

例えばデータの補正を行うような対応を例に取ります。作業記録に「テーブルhogeのカラムfugaの値が4のレコードに限り3に更新する」と記載するだけでなく、実際に実行したSQLを記載したほうが情報の正確性という点で優れていると思います。

振り返った時、「やろうとしたことと実際に行ったことの不一致」に気づくこともできるはずです。

例えば上記のDB更新をやろうとして「UPDATE hoge SET fuga = 4 WHERE fuga = 3」を実行した場合は 3 のレコードが 4 に書き換わっており、期待と現実が一致していないことになります。

ラベル付けを行う

弊社では github issue に記録しているので label を活用しています。「障害」や「調査」、「問い合わせ対応」「DB手動対応」などで分類し、集計に役立てています。

「DB手動対応」などはDBへ直接SQLを叩くような対応です。この操作は大変危険でなるべく少なくしたいため、あとから振り返って機能として実装できないかなどの判断で活用できます。

オーガナイゼーション設定で「Repository defaults」という項目があり、そこで「ラベル」の設定が行なえます。設定して以降に作成されたリポジトリはそのラベルがデフォルトで用意されるようになるのでおすすめです。

以上のことに気をつけ、弊社では運用の中で知見をためていくようにしています。今度は溜まった issue の情報をどのように集計し、活用しているかについて紹介できたらと思います。

読んでいただきありがとうございました。