なぜこの記事を書いたのか
自分が新人のときに学んだことを同じ新人の皆さんに共有して少しでも役に立てばいいな、と思っての共有です。
ポイント1「実家の母ちゃんでも作業が出来るレベル」
自分が上長から一番言われたことです。「実家の母ちゃん」という言い方に一部誤解を招きそうですが、要は「ITを知らない人でも作業を完遂させることが出来るように」ということです。
と言いつつ、「じゃあ一語一語説明を書くの?」と言われるとそうではないのですが、「プロセスは省略しない」ように記載したいですね。例えば「SSHでサーバにログインする」と書いてあったとします。分かる人はこれで良いのですが、分からない人はssh user@123.456.789.010なのかssh -i XXX.pem -p 2222 user@hostnameなのか判断ができません。出来る人でも勘違いしてポート指定をしないで「なんでだ？」となってしまうかもしれません。そのためプロセスは省略しない方が全員にとって分かり易いと思います。
ポイント2「あくまで作業手順書」
私たちが作成するのは手順書です。自分の思いを綴ったポエムでもありませんし歌でもありません。作業プロセスを明確にし、主観的ではなく客観的に手順書を書きましょう。「XXにした方がいい」など作業者に判断させるような記載は避けましょう。私の場合、作業者はその手順通りに動くロボットだと思って手順書を作成しています。想定通りの作業がなされなかった場合、それは作業者の責任ではなく手順書を作成した人の責任です。
ポイント3「手順書は誰かが読むもの」
手順書である以上、必ず読み手は存在します。自分で使う場合も「手順書を作成しているときの自分」と「手順書を使うときの自分」では別人です。「どうせ使うの自分なんだしこの辺は省略しちゃっていいや」だと未来の自分が「あれ？なんだっけ？」となるかもしれません。
ポイント4「誰がどこで何をどうするのか」
つまり5W1Hを明確にしましょうね、ということです。この方が誤解を招きませんし、誰が手順書を使用しても人によって変化することはありません。
ポイント5「郷に入ったら郷に従う」
これはSESやフリーランスに限定して言えることかもしれませんが、現場によって手順書のフォーマット、書き方、文化が異なります。Excel、Wordで手順書を作る現場もあればRedmineやConfluence等のmarkdownで作る現場もあります。「前の現場はこれで大丈夫だったのに！」と騒いでもプロジェクト全体を変えることは難しいでしょう。大人しくその現場の文化に従って書いた方がエコでスムーズだと思います。
ポイント6「書き終えたらセルフチェックする」
誤字脱字をレビュワーに見て頂くのは非常に時間が勿体ないです。（レビュワーの1時間は自分の1時間より貴重です）
自分でチェックして直せる範囲のものは自分で直して、それ以外の観点でレビュワーに見て頂きましょう。
ポイント７「再利用性が高い手順書を作成する」
運用保守の作業をしている方ならイメージ付きやすいと思いますが、一回手順を作成したら度々使われることが多いです。例えば「OSユーザ追加手順」があったとすればお客様から依頼がある度にその手順書を登場し使われることになります。再利用性が低い手順だと依頼がある度に手順書を何箇所も修正して、確認して作業開始となります。再利用性が高い手順だとこのステップが短いですし、使用している技術の仕様変更があった場合対応し易くなります。（私の場合だとAWS管理コンソールで画面キャプチャを取りながら手順書を作っていましたがあまりにもUIの変更が多いためコマンドを使用した手順書に変更しました）
最後に
自動化できるならした方がいいです。コンピュータに出来る仕事はコンピュータに任せましょう。