Webアプリエンジニア養成読本 Advent Calendar 2014 11日目の記事です。
今日は、手順書等でよく見る、コマンド入力手順をいかにミスりづらく作るか、というお話です。
ピシッ！と
お、おう…
これは、執筆中に使っていたGitHubのIssueでのやり取りの一幕です。uzullaさんはPHPerとして有名ですが、ITインフラに関しても造詣が深いのです。そこで、uzullaさんキビシイッ！って言いたいのが今日の話ではありません。
ITインフラ構築・運用を積極的に推進している方が増えている今日この頃。一方で、古いシステムをはじめとして、まだまだ手動の操作が残っている所もあるかと思います(※1)。
そこで登場するのが、手順書です。構築、運用、そして誰かに作業を依頼する際の一時的なものなど、様々な場面で書く事が求められます。もちろん、書籍執筆時の解説でもまだまだ現役です。
大切にしている事
僕が手順書を書く時に大切にしている事は、次の3つです。
- 操作が検証できること
- 入力がシンプルで迷いにくい事
- 手数が少ない事
1は、手順忘れ等を確認できるようにしています。例えばnginxの起動時に、プロセスが立ち上がっているか、そしてcurlで80番ポートにアクセスできるか、等を確認して問題が無い事を自分自身で検証できるようにします(※2)。
2は、ここのあの辺り…という定性的なものだと、手順を入力する人が迷ってしまいます。そういうものを防ぎます。
3は、あまり手順が長いと飛ばしてしまうミス等も起きやすくなります。短いのに越した事はありません。
しかし、今回は2に課題がありました。
打ち間違える可能性
先のuzullaさんの指摘に戻りましょう。
当初、echoやsedで設定ファイルを書き換える方法を記載していました。しかし、これだと万一コマンドを打ち誤ると不適切な結果になるばかりか、不慣れな人にとっては自分自身で検証するのが困難になる事があります。
このuzullaさんの指摘にははっとしました。
僕はこれまで、手順書をテキストファイル等のコピペで手順を複写しやすい形で渡してばかりいて、手書きで写経…即ちコマンドを打ち誤る可能性をすっかり見落としてしまっていたのです。
また、書籍の手順において、どのような人が読むか自分自身の想像を超える事も不思議ではありません。この点も、手順を実行している人と仕事で直接説明できる機会がある状況とは違います。
最終的には、多くの部分をvimで編集しdiffや記述例で評価できるよう、変更しました。
媒体の特性も織り込もう
ここまで、書籍を書く際に気づいた手順の留意点について、お話ししてきました。手順を起こすにあたってミスしづらい状況を作るのは重要ですが、それにあたって伝える人と方法も加味する必要がある事を確認しました。
僕は、手順書作成ともう少しお付き合いする必要がありそうですが、この本の執筆はその書き方について良い学びの機会となりました。
あっ、著者をはじめ1981年生まれの人が幹事をやる「ハチイチ忘年会」ってのを12/13(土)にやります。IT, Web関連の方でしたら、老若男女どなたでもWelcomeです！ぜひいらしてください。
また、Webアプリエンジニア養成読本 Advent Calendar 2014では読者の皆様からの感想・実践エントリも大募集中です！ふるってご参加ください！！！
それでは皆様、ごきげんよう。
※1: 僕は自動化推進派ですが、判断を求められる場面で手動が残る事はあり得ると考えています。
※2: 昨年からServerspecで検証する事も増えました。繰り返し検証しやすいためです。