2021-05-20 ssmonline - 手順書の書き方LT - お前らの手順書の書き方は間違えている(@nlog2n2氏)

概要

ssmjp 20210520 nlog2n2 tejun from Sekiguchi Toshihiro

www.slideshare.net

• 補足…「運用現場で用いる、主としてシェルスクリプトで記述される手順」を対象としている
  • 説明なしで「手順書」という語を使うには大げさな主題と感じた
• ITエンジニアが作る「手順書」は、説明不足も甚だしい事例が多く存在する
  • 特にアプリケーションエンジニアが作る手順書に甚だしい説明不足の事例が多い
• では、「一般的な運用現場のエンジニアが、その内容を理解できる」ような手順書を書くには、何に気をつければよいのか

説明不足も甚だしい手順書の事例（発表内容より）

tar -zxvf 20211231.tar.gz
cd 20211231
./bin/release.sh
cat ./log/release.log # (successと出てきたらOK)

↑説明不足な点は何か、自分でも考えてみよう¹

手順書を書くときの基本方針(@nlog2n2氏提唱)

• 作業ログを残す準備をする
  • ターミナルアプリのログ記録機能を使う
  • ターミナル画面を動画で記録する
• 日本語で作業内容を書く
  • メンテナンス計画書…技術的な事柄は書かない
  • メンテナンス手順書…技術的な事柄も書く
• 作業内容を共有できる項番を付ける
  • 主たる目的：作業報告時にどの作業であるかの報告を容易にするため
  • 副次的目的：手順書をそれっぽい体裁に見せるため
• どこで何をしたか分かるように書く
  • 誰がどこにログインするかを明記する
  • 絶対パスで書く²
  • ユーザー、権限周りは事前に確認する
  • 前後の確認はawk・grep・diff等を有効に活用する
  • ダイイングメッセージ性のあるコマンドを使う
  • 手順書を作るシェルを書く

「ダイイングメッセージ性のあるコマンド」とは

• 「ダイイングメッセージ性」…とてもエモい表現！
• 私の解釈
  • 「historyをたどっていくことで、手順の全てを遡ることができる」という条件を満たしたコマンド群
  • 手順書作者が消滅したとしても、別の誰かが手順を追うことができるコマンド群
  • 「ロールフォワード」という概念と深い関係がありそう
• 具体的には何を指しているのか
  • スクリーンエディタなどで設定ファイルを編集してはいけない
    • historyで変更内容を追うことができなくなるため
  • sed・echo・touchなどの実行結果をつなげて記述していく
    • これらの実行結果であれば、historyで変更内容を追うことができる

---

1. 説明不足な点としては、例えば「カレントディレクトリはどこか」「どのユーザーアカウントで実行するのか」「必要な権限は何か」「./log/release.logの中身に、success以外の文字列があったらどうすればよいのか」等を挙げることができます。↩

2. Windowsの場合、「ドライブ」という概念の存在ゆえに、「絶対パスが環境に依存する場合がある」というつらみがあります。特にリムーバブルメディアが絡む場合につらいです。↩