インフラ手順書テンプレートを作った話

これは何

インフラ的な手順作業書の書き方についてまとめたい。 このページのテンプレートをコピーして書き始めると、手順書がスムーズにかけることを目標としています。 ここに書いてあるものはコンフルエンスを前提として書いています。

インフラ作業をやるときには原則的に手順書を書いてチームメンバーにレビューしてもらいましょう。 予定していない作業をぶっつけ本番でやると、大幅に時間がかかったり事故がおこったりすることが多々あります。

手順を残しておけばどういう進捗状態になっているかすぐ分かりますし、これから近い作業をする人が参考にすることができます。 まったく手順資料がなかったとすると、すべての作業をゼロから考えなくてはならず、大きなコストがかかってしまいます。手順を作ること自体がコストではありますが、長期で見てコストが低くなると考えて資料化するべきだと考えています。

=============以下手順テンプレート=====================

タイトルは、実施日時が決まっている手順は年月日を書いておきましょう。例えば単に「メンテナンス手順」と書いてあると後から見た時にいつのかわからなくなりますが、「20180206 全体メンテナンス手順 MySQL Master昇格」 などと書いてあると大体タイトルだけ見て参考にできるか判断することが出来ます。

目次

目次はつけましょう。目次を見てよくわからない（階層がガタガタしているとか、節のタイトルが意味不明とか）の場合にはたいてい読みづらい資料になっています。

作業目的＆作業概要（方針）

この作業書にかかれている作業の目的と概要を書きましょう。 目的を達成する手段は（場合によっては）沢山あるので、目的をはっきりさせて手順方針を決めた時点でチームレビューを受けたほうが手戻りが少なくて良いです。 目的と方針は表裏一体なので対で書くと良いのではと考えています。

作業目的

目的です。

作業概要

この手順の概要について数行程度で書きましょう。細かい手順だけがあると、それをすべて読まないと全体をつかむことが出来ません。

期限＆スケジュール感

厳密な期限がある場合にはそれを根拠と共に書いておきましょう。チケットなどあれば貼っておくとよいです。　 特に強い根拠がなくても期限の目安や目標時期だけ書いておいてもいいと思います。仕事を振った人が「このタスクはどれくらいかかるかな？ いつ終わるのかな？」というのが把握できるようにする目的です。 ある程度タスクが洗い出されている場合には、いつごろにどのタスクをやるというロードマップを書いておくとよいです。厳密でなくてもよいので工数見積もりが書いてあるといいかもしれません（理由は同上）。

関連リンク

チケットや全体を通した参考資料を貼っておきましょう。前提知識やこれまでやられた似た作業手順を貼っておくのも良いと思います。 手順の個別項目に関連する資料はその場に貼っておいたほうが便利です。

手順に関わる調査資料などを子ページに置いていきましょう（コンフルエンスなど階層化できる場合）。子ページへのリンクが自動で表示されない設定になっている場合には子ページを表示するとしておいたほうが階層がすぐ分かって便利です。子ページのマクロは孫ページまで表示するように設定することもできます。

検討事項

検討内容によって手順が変わるような先に考えておくべき重要な検討事項について書いておきましょう。なければ不要です。 検討が終わったらそれをタスクに落とし込むか、「その他」項目や子ページにまとめるなどしましょう。

検討事項１

ほげ

検討事項２

ふが

事前準備

当日でなくてもできる作業については事前にやってしまいましょう。やった結果もまとめておきましょう。 特に他部署依頼など時間がかかりがちなものは先に潰しておきましょう。作業ボトルネックは何か？ それを潰すには何をすればいいんだろう？という視点で考えるといい気がします。

事前準備１

ほげ

事前準備２

ふが

同期的作業タイムスケジュール

他チームと同期的にやらなくてはいけないとかメンテナンスの時間が決まっているなど、当日のタイムスケジュールを決める必要がある手順については書いておきましょう。非同期でできるものは事前作業としてやってしまいましょう。 同期的作業が特になければ、事前作業、事後作業ともに一つの項目にまとめてしまって良い。

実際にかかるだろうなという時間に追加してバッファや万が一の切り戻しの時間も考慮して決めましょう。

| 時間 | 作業内容概要&リンク | 担当者 | |:-----------|------------:|:------------:| |xx:xx ~ | 詳しい作業内容が長くなる場合には作業詳細に書いてリンクを貼っておきましょう。 | やること： @担当者 役割分担できそうなら相談して依頼しましょう。 | 長時間に渡る作業の場合には休憩時間なども考慮に入れましょう。人は休まないとミスをします。

依存関係があるサービスには連絡しておきましょう。その話をしたリンクもはっておきましょう。当日に連携が必要な場合にはその連絡内容もあらかじめ作っておくとテンパらなくてよいです。

同期的作業詳細

上のタイムスケジュールに書ききれなかった詳細な内容について書きましょう。上のタイムスケジュールにリンクを張りましょう。リンクは目次のものをコピーすると楽です。

設定更新がある場合には、その設定を確認できるコマンドなども一緒に書いておきましょう。可能であれば設定の一部だけでなく全部をカバーする確認方法を検討しておきましょう。

中作業１

作業は問題があった時に巻き戻せるように進めましょう。可能な限り一気にすべてを破壊的に進めるのではなく、徐々に次の状態に移行していきましょう。

少作業１

チェックボックスで細かく書いておいたほうがよい 終わったらチェックをつける

少作業２

好みではあるが、少作業にもタイトルをつけたほうが目次を見て流れがつかみやすい

中作業２

ふが

後処理

当日にやらなくてもよい手順についてまとめておきましょう。 忘れがちなのでリマインダやgaroon予定など入れておくとよいかもしれません。

その他

参考となる小話や調査について書く。分量が多いときには子ページに切り出しましょう。