Readmeを読み解く際の注意点と情報の抽出
運用保守やインフラ関連の仕事をやっているとドキュメントを読んで、手順書を作ることが多いかと思います。
手順書のフォーマットがあれば、それに合わせる形になるのですが、
それでも新しく手順を起こす際に確認すべき点を整理したので、手順書作成の機会があったら、
今回の内容を思い出して、作ってみてください。
意外と忘れがちなポイントを書いておきました。
1.抽出作業
①制約条件の洗い出し
このパッチを当てる前に、～のパッチが適用されていること。
特定のライブラリーバージョンが～以上であることの条件を確認
②影響範囲と互換性の確認
今回の適用をしてどの範囲が影響があるのか、テスト環境だけにとどまるのか？
本番環境まで及ぶとしたら、どの号機まで影響するのか？
災対環境の影響はなどを考えて書く必要があります。
③OS、MWの再起動の有無
適用後にOSの再起動が必要。Reboot Requiredなどの記載を見逃すと、
作業時間が足りなくなります。
2.構成の工夫
①誰が読んでも、夜間作業・休日作業で迷わない作業指示書にすること
コマンドの内容
実行される実行結果
→これらをセットで書く
systemctl status XXXX
XXXの期待値まで明示する。
環境依存の情報を変数化する
サーバIP、ディレクトリの表記を実際の現場の環境
192.168.10.1や/user/local/bin/work/..に書き換えて指示書を書きます。
確認コマンドを手順に挟む。
echo XXX
ipconfig XXX
など確認コマンドを適用させる直前に手順を入れ、スクショを取るタイミングを組み込みます。
3.リスク管理の注意
失敗したときのことを考慮して手順書を作成することが必要です。
例：Readmeにバックアップを取ってくださいと書かれていても、
どのディレクトリを、どのコマンドで、どこに保存するかまでパスを書いて具体的に指示します。
エラーの対処法を書く。
エラーが出た際、エラーの場合、回復作業で切り戻しを行う手順などを記載します。
ログの確認をする際には、どこのパスに移動して、ログを確認するのか明記します。
いかがでしょうか？
これらを踏まえた上でドキュメントを読んで手順書を作っていくとここの部分は今の現場ではどのIPになるのか？
どのパスまで移動させて実施すればよいのか分からなければ確認を取るなどの作業が立てやすくなります。
手順書の作成ができるようになると、わかりやすい書き方を意識するようになり、
ドキュメント作成スキルが上がっていくので一度は体験してみてください。