作業手順書を書くときに気をつけたいこと
最近社内で手順書をレビューしてて気になったことがあったので、書いておく。
作業の目的を明確にする
まず、なんのための作業なのか明確にしておく必要がある。例えば、
- 管理者を追加したい
- データをクリーニングしたい
- リリース作業したい
など作業の目的は様々であるが、それがはっきりしないことには、そもそも手順が正しいかどうか判断できない。
「今度削除するデータをお客様の要望により念のためバックアップしたいです。」
「はい、でも対象になるデータは、n 週間前のデータなので週次バッチでバックアップが残っていると思います。そもそもこの作業は不要で、削除だけの手順で十分だと思いますがどうでしょうか？」
「確かにそうですね」
みたいな不毛なことがないようにしたい。
日本語の表現を曖昧にしない
例えば履歴のデータをクリーニングするとする。
#先月までのデータを削除する
DELETE FROM hoge_table WHERE created_at < '2017-02-01';
「ちょっと待って、先月までって、1 月までってことで 1 月は含まないんじゃないでしょうか？？？いや私が勘違いしているかもしれないし、「まで」ってのは含むの含まないの？」
日本語は難しい。口語でサラッと書いてしまうと境界条件が曖昧になってしまう。
SQL 見れば自明だろ！って思うかもしれないけど、日本語と SQL とどっちが正しいか確信が持てない。
スコープを揃える
スコープと言う表現が適切ではないかもしれないが。
先の例でいうと、履歴データは年月日のデータを持っているので、「先月まで」「半年」みたいな月や年単位の表現ではなく、日をベースに範囲とかを記述すべきだと思う。
#2017-02-01 未満のデータを削除する
DELETE FROM hoge_table WHERE created_at < '2017-02-01';
と書いてもらえると、SQL と日本語で違いがない。日本語の表現としては少し変な感じがするかもしれない。でも、境界条件はハッキリしたい。
時刻は固定された表現にする
ついでに書くと「先月」という表現は作業をする時点で変わってしまう。2 月だと 1 月だし、6 月だと 5 月になってしまう。
作業をする時点での、明確な時刻を指定した方が揺るぎがないので、極力時刻を固定した方が良いと思う。
作業が延期されたりすることもあるが、その際にはその時の日時で手順書を更新すべきだと思う。
後から振り返ったときに、いつやった作業なのか明確になっている方が良い。
「2017-02-01 データクリーニング手順書.txt」となっていても、実際には 3 月に作業したみたいなこともあって、そういう時にファイル名も更新すべきだし、手順書の内容もちゃんと日時を合わせるべき。
根拠を明確にする
手順書に落とし込む必要はないかもしれないが、作業の根拠は明確でないといけない。
「データクリーニングの対象レコードが 1 億件あるので、メモリが足りない可能性があります。」
「メモリが足りないという根拠はなんですか？」
「前回 2 千万件のレコード削除の際にはメモリが枯渇していました。」
「（トレンドのグラフを見つつ）前回の作業の時には明確なメモリ使用量の変化はないようですが…」
「COPY を使ったので…（モニョモニョ…）」
「逆に同じレコード件数で、別の作業の時に pg_dump を使用していますが、コレはメモリには影響なかったんでしょうか？」
「それは…」
例えばレコード数が同じだった時に COPY はダメで pg_dump は大丈夫という根拠が明確でないといけない。
同じ操作ではないのでもちろんリソースの使い方も違うと思うし、一方が良くて一方が良くないという理由はちゃんと説明できないといけない。
そもそもどちらの作業も考慮が足りてなかったんじゃないか？と思ってしまう。たまたま影響がなかっただけで。
実際、何が影響して障害になったりするかわからない部分も正直あるんだけど、少なくとも自分がやる作業については、どういう作業でどういう影響があって、どういうリスクを伴うかというのは根拠を持ってないといけない。
根拠が間違っているかもしれないんだけど、そこが揺らぐと何もできないし、自分で説明できるレベルで根拠はしっかりしておいてほしい。
他にもあった気がするけど、とりあえず終わり。