｢手順書｣のススメ

さて, 早速本題に入っていきましょう. 皆さんは｢手順書｣を書いていますか? 自分はと言うと, 最近そこそこの規模のオペレーションが必要なタスクを担当する機会が多く, その度に手順書を書いて, レビューしてもらってからオペレーションをするようにしています. 例えば, 今年実施した｢はてなが提供するドメインを利用したブログのHTTPS化対応｣のリリースの時は, このような手順書を書いていました:

この時は, GitHubのIssueに手順書を用意していました. GitHubの場合, IssueやPull Requestに,

- [ ] ほげほげ...

といったフォーマットで手順書を書いておくと, [ ]の部分が自動的にチェックボックスになるので, 非常に便利です. ちなみにチェックを入れると[ ]が[x]に変わります.

｢手順書｣の利点

手順書を用意する際の問題点は, やはり｢用意に時間がかかる｣という点でしょう. オペレーションを実施するにあたって, 役立つ手順書を作り込むには, レビューの時間を含めてそこそこに時間がかかります. とはいえ, 手順書を用意すると, そのコストを上回る利点があると思っています. 具体的には...

オペレーションの際, 考えることが減る
- 予め, 必要な作業やそれを実現するためのコマンドを網羅しておくことで, オペレーション中に｢どうすればいいんだっけ?｣と悩む機会が減ります
  - オペレーション中に悩み始めると, 特に時間がかかればかかるほど, 焦りに繋がります. 焦りはオペレーションミスの原因になりがちなので, それを防ぐのは非常に重要です
- また, オペレーションの中止基準についても事前に手順書で定めておくと, 実際にトラブルが起きた時悩まずに判断出来ます
  - 例えば, ｢○○の作業後, エラーレートがXX%を越えたらオペレーションを中止して切り戻す｣とか...
  - これもまた, 事前に手順書で定めておかないと都度考慮する必要があり, 焦りに繋がります
事前にオペレーションの内容を共有できる/レビュー出来る
- 個人的には, これが一番大きなメリットだと思います
- 実施する作業を一度手順書という形で文章に落とし込むことで, チームメイトからレビューしてもらうことができます
  - レビューすることで, より良い作業手順を練り上げることができます
- 知識の共有という点でも有用です
  - 新しく入ったメンバーは, 手順書を読むことで, ｢○○を実施するためには, ✕✕をすればよい｣といった勘所を掴むことができます
  - また, レビューの中で, ｢実はこのオペレーションは不要｣だとか, ｢こうやった方が楽｣といった知見の共有も出来ます
時と場合によっては再利用が出来る
- 例えばミドルウェアのバージョンアップの手順書を一度用意しておけば, 将来更に次のバージョンへアップグレードをする際, 概ね再利用できるはずです

自分自身, 最近ちょっとしたバージョンアップを実施するための手順書を書く機会があったのですが, その中でこれまでうろ覚えだったインフラ周りのオペレーション方法について整理することが出来て, 非常に有用でした. チーム異動や転職などで新しい環境に至った時, ｢手順書を書いてみる｣というのは, そのチームに慣れる良い方法の1つかも...? と思います(すでにチームで手順書が用意されているなら, 少し冗長に(丁寧に)したものを作ってみる, というのも有用でしょう).

｢手順書｣を書く時に気をつけていること

必要な連絡/周知なども網羅する
- ｢手順書｣と言うと, 実際にコマンドを入力したりして作業する部分に注目しがちですが, 実際に業務の中でオペレーションをする際は, それ以外の手順も必要になりがちです
- 例えば, リリース前に然るべきメンバーに周知したり, 関係部署に共有したりするのも, 立派な手順の1つです
  - そういった作業を忘れないように, 手順書に織り込んでおきましょう
実際に入力するコマンドまで丁寧に書く
- ｢○○する｣だけでなく, ｢○○するために, サーバ上でxxxxxxというコマンドを入力する｣まで書いておく... というイメージです
- 特に, コマンドのオプションが多い/長い時は, 予め手順書にコマンドとオプションを書いておいて, 実行するときはそれをコピペする... くらいにしておいた方がミスを防げます
  - 実際に作業を始めた時, コマンドやオプションを間違えて覚えてしまっていると非常に焦ります... なので, 手順書に書いておいて, 事前にレビューしてもらうのが大事です
中止基準や切り戻し方法も定めておく
- 中止基準を定めておくと, 問題が発生した時に, 進むか中止するかの判断を悩まずに済む... というのは, 利点でも述べました
- そういった事態はなるべく防ぎたいですが, とはいえそうなってしまった時のために, 作業を中止し, 作業開始前の状態に戻す方法についても, 手順書に書いておくのが大事です
  - 特に複雑なオペレーションをする場合, 作業を中止する, と決めたはいいものの, そこから原状復帰する方法がまとまっていないと, 非常に焦ります
    - 得てしてこういう時にミスが起きて, 二次災害が起きたりします...
  - そうならないように, 原状復帰の方法についても手順書に盛り込み, またレビューしてもらいましょう

実際に手順書を書いている中で自分自身で気づいたり, 或いはレビューの中で指摘してもらったりして, 上記のようなポイントを意識しながら手順書を書くようにしています. これらを意識しながら手順書を用意すると, そこそこ時間はかかる(オペレーションの規模にもよりますが, それなりの規模の作業をするのであれば, 準備とレビューで3日くらいは普通に準備期間として必要になると思って良いと思います)とは思いますが, 先に述べたようにそれを上回るメリットがあると思っています.

...まあ, ここまで書いておいて, ｢割とエンジニアって日常的に手順書を書くのでは...?｣と思ったりしたのですが, もし, ｢手順書, 書いたことないな...｣とか, ｢既に用意してある/用意してもらった手順書を, 作業するだけだったな...｣という方が, もしもいらっしゃったら, 自分自身の手で手順書を書いてみると, いろいろ気づきや学びがあると思うので, 是非やってみて頂きたいと思います.