アットマーク・テクノロジー株式会社の佐藤です。
記事に目を通していただきありがとうございます。
いきなりですが・・・皆さん
「ドキュメント作成において、こういう経験ありませんか？」
運用/保守や構築において、エンジニアなら誰もが経験する手順書などのドキュメント作成。
自分が作成したドキュメントを社内や有識者にレビューした時に「ここを修正して下さい」 と指摘をされた事ありませんか・・・
今回は、運用/保守業務をメインで最近構築の上流工程に携わって私が
感じた事やとても勉強になった事をお話したいと思います。
1.ドキュメント作成
ドキュメント作成において、運用開始までには以下の流れがあります。
1.資料作成
2.レビュー
3.指摘取り込み
4.最終レビュー
既存のフォーマットがあったり、作成するのは難しくないと思いますが・・・
一番気にするところと言えば、2.レビュー ですよね。
お恥ずかしい話、私は説明やプレゼンするのが苦手で慣れるのに時間がかかりました。
作業手順書のレビューをした際、「何故、このコマンドを使用するのか？」を聞かれ、
言葉に詰まった経験がございます。
何故、そうなってしまったのかを次で考えてみましょう。
2.作業内容やコマンドの理解度
Linux環境での作業手順書レビューにおいて指摘をされた際に
言葉に詰まったり、「確認します」で終わらせてしまった時にふと思いました。
「コマンドの意味や何故この手順なのかを理解していないんじゃないか」
手順書を作成したのは良いが、過去の作業手順書を流用した為
そこまで作業内容を重要視しておらず、 「本当にこのコマンドで合っているのか？」の
確認まではできておりませんでした。
正直な話、経験が浅くても手順書通りにコマンドを入力していけば作業は完了します。
ただ、それだけでは自身のスキルアップになりません。
「担当者がその作業内容と手順を理解してないといけないのです。」
コマンド1つ入力するだけですが、何故このコマンドやオプションを使っているのか？
それがわからないといけません。
Linuxサーバーの運用経験が殆ど無かった私が、ここ1年で頻繁に使うようになった
コマンドの事例として以下を上げます。
ls -ltr
知識がある方からすれば、ぱっと見なんのコマンドとオプションかはわかりますね。
「ディレクトリ内のファイルを詳細情報付きで、更新日時の古い順に並べて表示」 です。
lsは基本的なコマンドですが、作業内容によってはオプションの組み合わせで異なります。
なので、基本的なコマンドでもなんでこのオプションをつけているのか？コマンドの理解が重要なのです。
さて、後はどうやったらレビューを上手くできるのかですね。
次に自分が先輩からいただいたアドバイスや成長したなって実感した話をします。
3.レビューにおける重要なポイントとは
現場に入りたての自分が、最初に直面したレビューでの指摘が
「手順を細かく言う必要はない」でした。
レビューにおいて重要なのは、ただ手順を上から説明するのではなく
作業において重要な手順やコマンドの認識合わせなのです。
ログインやバックアップを取る手順を一つ一つ言わずに、簡易的にその手順を説明した後、
重要な手順（見てもらいたい箇所）を説明するだけです。これだけで、有識者は全体の作業内容を把握しレビューにあたります。
レビューにおける重要なポイントとは、 「自身の理解＝有識者との認識」
すなわち、「作業イメージがちゃんと合っているか？」 です。
手順書とレビューの話からは反れますが、実際に私が体験した認識の部分をお話します。
有識者が不在の日にお客様より 「ログ取得」 の依頼がありました。
自分の中で 「grepコマンドを利用して検索すれば良いのでは？」 とイメージがついておりました。念の為、有識者に確認した所、認識に相違なく作業ができました。
有識者からも 「作業イメージも合ってる」 「コマンドが理解できるようになってきてる」 と言われたのが、成長してきてると実感できた所でもあります。
4.分かり易く作成するのは難しい
ある程度経験を積み重ねた人が手順書を作成した場合
内容によって「分かる人は分かる」 けれど、未経験者に「この手順で作業して」と言ったら内容がわからなく、作業できない。こういう風になりませんか？
現に私自身も手順書を作成した時に 「〇〇さんにお願いしても作業できないよ。」 って指摘されました。
そうなんです！慣れてきた時に作成する手順書は、簡易的な手順内容なってしまうのです。
未経験の初心者さんでも手順書を見れば作業でき、スキルアップにもつながる
そんな手順書を作成するのは難しいと感じた事もあります。
そんな時は 「自分が未経験者の気持ちになって作業をイメージしながら作成する」
こんな感じで作成するように心がけております。
5.まとめ
ここまで、ドキュメント作成において体験談を踏まえ書かせていただきました。
経験を積み重ね自身のスキルアップと共に、ドキュメント作成も慣れて来ておりますが
後輩にも分かり易くレクチャーしたり、教育していくのは大変だなと思うようになってきました。
自身のスキルアップも兼ねてドキュメント作成などに困った時は
自社の凄腕マネージャーに相談してみようって思います。