作業の手順書を書くときに気を付けていること
まえがき
作業するときの手順書作成、なかなか慣れませんよね...
自分の備忘録も兼ねて、手順書を作成するにあたって気を付けていることを書き出してみます。
思考を挟まず実行できることしか書かない(具体的な指示を書く)
具体的でない手順が書いてあった場合、何をすればいいかわからないし、実行者の解釈の余地によってさまざまなことが行われてしまいえます。
たとえば以下のような手順です。
まずい手順1: 「xxx をインストールする」とだけ書いてある
問題点
どういうコマンドでインストールするのかが明確でありません。
実際にとられた手順によってはversionの違いが出うるし、出来上がりの環境の状態が変わりえます。
改善方法
opam pin add fstar https://github.com/FStarLang/FStar.git --with-version "2022.11.07"
など、具体的に実行する手順を明記する。
まずい手順2: 「問題ないか確認する」
問題点
何をもって「問題ない」と判断するか解釈の余地が生まれてしまいます。
改善方法
以下のようにすることができます。
-
このリンク(http://hoge.fuga.piyo)の foo metricsを監視し、5分間エラーレートに変動がないことを確認する- エラーレートがどのくらいまで上がると問題なのかなどの解釈の余地は残っていますが、「問題ないか確認する」よりかはマシです
- path が通っているか
which fooAppで確認する - status が Ready になっていることを確認する
作業を skip する条件を手順の下に書かない
次のような手順があったとします。
- storage オプションにチェックを入れる
- 名前欄に 「サーバー名」を記入する
- 送信ボタンを押す
- 申請完了通知が slack に届く
- 申請完了通知のリンクを開き、申請が受理されていることを確認する。
オプションについて ：storage オプションは foo アプリを起動しない場合は要らない
これを上から読んでいくと、送信ボタンを押してしまった後に storage オプションが不要だったことに気づくことがあるのではないでしょうか...
このような事故を防ぐために、 実行条件は必ず当該の手順より前に書くようにします
改善例
- 【foo アプリを起動する予定の場合のみ】 storage オプションにチェックを入れる
- 名前欄に 「サーバー名」を記入する
- 送信ボタンを押す
- 申請完了通知が slack に届く
- 申請完了通知のリンクを開き、申請が受理されていることを確認する。
条件分岐を挟んでちょっとの作業工数削減を狙おうとない
経験上、条件分岐があると脳味噌の負荷になる事が多いです。同じ手順を何度も繰り返すような時も、条件分岐のところで一回考えるために手が止まってしまうし、繰り返すたびに微妙にバリエーションがあるのは結構ストレスになります。
条件分岐の目的が作業工数削減で、それがほんのちょっとの削減でしかないのならば、むしろ分岐を挟まない方がスムーズに作業ができることが僕の経験上では多いです。
細かいステップごとにうまくいっているか確認する手順を挟む
うまくいっているかどうかの確認手順が最後にしかないのは危険です。
失敗した状態に手順を重ねていくと、重ねた手順が全て無駄になりうるのみならず、失敗の傷口を広げて修復をより困難にしてしまう恐れがあります。
更新系の手順をするときはそれがうまくいったかどうかを確認する手順をなるべく細かく挟みたいです。
失敗したときにどう切り戻すかの手順もある
手順が失敗したときに切り戻し方を事前に決めておかないと、最悪の場合には不可逆的に環境を壊してしまう恐れがあります。
大事な環境を操作する場合、壊したときに素早く切り戻す手段を事前に検討しておき、それを手順の形で言語化してから作業を行いたいです。
手順レビューを受ける
自分一人で書いているときは脳内補完できていた情報が、他人が読んでみると手順の文面から抜け落ちていることってあると思います。
必ず他の人にレビューしてもらい、他人から見ても必要十分に書いてあるかをチェックしてみるのが賢明です。
全く違う側面として、手順を書いて一人で実行して何かあったら自分一人の責任になってしまいますが、他の人にレビューしてもらってＯＫを出してもらえばある意味共同責任だという面もあるかもしれません。
まとめ
手順書を書くときに気を付けている事項についてリストアップしてみました。自分も手順書を書くのはあまり得意ではないので、ここに書いたことを忘れずに手順書作成の精度を上げていこうと思います。
Discussion