インフラエンジニアの綺麗で優しい手順書の書き方

インフラエンジニアの 綺麗で優しい手順書の書き方

湖山 翔平 / Shohei.Koyama @sion_cojp

自己紹介

湖山 翔平 / @sion_cojp

元FPSプロゲーマーでアジアチャンピオン

qiitaをよく書いてます (http://qiita.com/sion_cojp)

インフラエンジニアとしてよく使うコマンド集

インフラエンジニア

株式会社リブセンス

Infrastructure as Codeが流行ってる中、 どうしても手順書じゃないといけない場面

ってありますよね

やっぱり手順書って大事

でも読みにく手順書では意味がありません

（最悪、障害時に混乱を招く    DeathNote に。）

①レビュー➡修正➡レビュー・・・の繰り返しで工数がかかる

②レビューする方も大変だし工数がかかる

③お互いに疲れる

良い手順を書くと、そりゃもう良い事尽くしです

・信頼確保

・レビューワーの負荷軽減

・レビュー後の修正も減る

・新入社員、新卒の方が喜ぶ

・汎用手順を書きやすい

・障害対応のとき焦らない

・障害対応のときの安心感

・情報が後者に残る

・qiitaにもそのまま載せやすい

・評価もあがる・・・はず！！

手順書は優しさです

如何に他人に気を遣えるかです

後者のためになるので頑張りましょう

きれいな手順書をいっぱい書く人はもっと評価されてもいいと思う！！

今回は自分なりに手順書を書くときやレビューするときに

注意してることを実際の経験談をもとにお話しします

ちなみに 弊社で手順書を書いてるツールは

Confluenceです

1. 書き方を統一しよう

手順書のフォーマットを作る

主題は4つ

　① 概要 　② 事前準備 　③ 作業内容 　④ 事後確認&作業

目次も忘れずにつけましょう

また、同じ手順を踏んでるのであれば、 目次や内容がそっくりになるようにします

実際にあった話だと、 同じデプロイツールで、社内アプリをデプロイする手順なのに、 作業内容の見出しが全くが違う。。

Bアプリのデプロイ手順Aアプリのデプロイ手順

違うデプロイツールなのかな？

修正後、同じ見出しに統一。

これで直感的に同じデプロイツールを使ってそうなのがわかりますね

Aアプリのデプロイ手順 Bアプリのデプロイ手順

2. コードブロックにはsyntaxハイライトをつけよう

syntaxハイライトを付けると、 文字が強調され見やすくなります。

一つ一つ付けるのは面倒くさいかもしれませんが、 ちゃんと付けましょう

ばっしゅハイライトしんたっくすあり

見やすい！

個人的には特定の言語こだわりがなければ bashを使います。 #（コメントアウト）が緑色に強調されるので使いやすいからです。 ごく稀にDiffも使います。

私はコメントアウトの使い方を下記に統一してます 　① 作業の説明は ### と3つつける 　② オプションや行の説明を加えるときは# 1つを使うこんな感じでオプション説明 作業説明は# 3つ！

3. プロンプトは$で統一

rootだと#だったりしますよね。 でもコメントアウトと見誤ってしまうので、

[root] $ service httpd restart

とかで統一してあげると、親切です コマンド入力忘れも減るでしょう。

4. 何をやってるか、コマンド毎に説明を書く簡単なコマンドならまだ良いとして、

「この設定値なんだろう？」 「このオプションなんだろう？」

など、手順書はググらなくてもいいように書いてあげましょう その手順書内で完結がベスト

また、「この人ちゃんと理解してやってるな」と レビューワーに安心感も与えれます

上からなぞっていくのが手順書なので、 コードブロックは少ない方が、 「あれ？今このブロックだっけ？」みたいなことにならないです

ssh先を変える毎にコードブロックを作るのもありです

わかりやすい！

5. 手順書内完結を目指す「この手順でドメイン移管よろしく」 　概要を見ると・・・

こんなこと書かれてても新卒さん達はさっぱりですよね。 結局ぐぐって。。でもあまり分からなくて。。

手順も同じです。 概要に書いてることは、wikiから引用せず、 新卒でも分かりやすいサイトや、 なければ理解しやすいように図や比較表に落とし込んで リンクを貼ってあげましょう

基本ググらせない 手順内で完結がモットー！

遠い言い回しはNG。簡潔に。 なるべく言葉数は最小限になるように考えましょう。

行数は1～3行に収まるようにしましょう。（ベストは1行）

例をあげると、

のほうが言葉が短いので見易いです。 「そのまま打ったコマンド貼り付けたほうが楽」 と編集が億劫になるかもしれませんが、めげずに！

6. 文字数、行数、見出しの数は最小限に

こっちより こっち！

7. ルー語禁止

誰でも伝わる日本語で書きましょう。 個人的には意識高い系用語も避けてます。

8. 手順外、内で行ったり来たりしないようにする

行ったり来たりすると、読みにくくなります。

手順書は縦になぞっていくので、 縦はもちろん、横の行ったり来たりの動きは あまり入れないほうがいいです。

それは表や図の挿入でも起こります。

なるべく表や図は概要などのトップに持って行って、 あとはコードさえ読めばいい形にすると 読みやすい手順になるでしょう

一見よさそうだが・・・ 見出しにも 値を入れた方が 戻らなくていいので親切

わかりやすい！

読みづらくなるので。

9. 分岐が多いなら別の手順書に書きましょう

10. 自分の感想や、昧な表現はさけましょう

「私は⚪⚪だと思うけど、今回はこうします」

「⚪⚪とか、xxなど」 「手順書なのに・・・なんか検証内容が微妙に書いてるんだけど・・・」

読書感想文ではありません。 本当に必要な情報なら、別の場所に書きましょう。

11. 図は線は太く少なく、文字も太く見やすく

拡大しないと見えない図なんて、あまり見られないでしょう。 大きく、太く。そして簡潔に。 色も統一性を考えてあげると、見やすくなるでしょう

図の製作はCacooがおすすめです。

わかりやすい！

ここからは 出来上がった手順書のチェック関連！！

12. 主題と内容に相違がないかチェック

「移行手順しかないけど、これ新しくサーバ構築してるよね？」 「デプロイ設定って書いてるけど、普通に本番でデプロイ実行してるよね？」

レビューワーが困っちゃいます。 ちゃんとチェックしましょう

13. 手順書が置かれてるディレクトリをチェック

構築手順なのに、障害対応のところにあったり スポット手順なのに、汎用手順類にあったり

ちゃんと置いてあげましょう

ちなみに弊社のトップ階層はこんな感じです

14. 新卒でも分かるように書いてあるかチェック

手順書を一番見るのは新卒さんや、新入社員さんなんですよね。 ここは新卒に合わせておけば大丈夫！

15. 誤字脱字がないかチェック

レビューワーの負荷軽減のために、軽くチェック

16. 脳内でシミュレーションをして動作チェック

検証環境でやるのもいいんですが、 脳内シミュレーションは絶対やりましょう。

障害訓練の一環にもなります。

まとめると

1. 書き方を統一しよう 2. コードブロックにはsyntaxハイライトをつけよう 3. プロンプトは$で統一 4. 何をやってるか、コマンド毎に説明を書く 5. 手順書内完結を目指す 6. 文字数、行数、見出しの数は最小限に 7. ルー語禁止 8. 手順外、内で行ったり来たりしないようにする 9. 分岐が多いなら別の手順書に書きましょう 10.自分の感想や、昧な表現はさけましょう 11. 図は線は太く少なく、文字も太く見やすく

[チェック編] 12. 主題と内容に相違がないかチェック 13. 手順書が置かれてるディレクトリをチェック 14. 新卒でも分かるように書いてあるかチェック 15. 誤字脱字がないかチェック 16. 脳内でシミュレーションをして動作チェック

以上です！

最後に

皆さんも優しい手順書を書きましょう！