歴戦のSE向け手順書を作成する際に気をつけたこと

お疲れ様です！
やっと秋めいてきて快適ですが、現場のクーラーは集中管理されているので相変わらず極寒です。
今回は現場のSEさんたちに手順書を作る仕事をしたので、その際に気をつけたポイント、やった事をまとめした。かなりやっつけ仕事でしたが、今後手順書を作成する際の参考になれば幸いです。

手順書を作ることになった経緯

機密事項に触れてしまうので色々割愛しますが、プロジェクトにある全ての機器をリスト化して管理しよう！！となり、数百台ある機器のシリアル番号などのデバイス情報や中身のソフトウェア情報を集める事になりました。
現場上長から宇宙語で記されているぶっっっっ厚い機器管理の資料を渡され、「とりま必要な手順抜き出して、簡単な手順書を作成して皆さんに実施してもらって〜締切は5日後」と言い渡されました。
その5日間上長は現場に居ない、ということで自分でいろんな人に聞いてなんとかしなければならない状況でした。とりあえず資料全て目を通したものの意味不明の極地。
なんでも教えてくれるプロパーのお姉さんに聞いてみたところ一緒に資料を読んでいだけて、助言をもらいながら、なんとか締め日までにリスト化、登録手続きを出来ました。

1.実施完了までの計画を立てる

5日間の猶予がありましたが、5日間かけて機器情報を集めるのではなく、集めた情報をリスト化して登録しなければならなかったので、1日で手順書を作り、3日間全ての機器情報を集めて、残りの1日で私がリスト化して登録まで済ます、というスケジュールを立てました。

2.資料を読んで必要な事を抜き出す。

この作業が一番地獄でした。
読めど読めど頭に入らない。ここまでつまらない読み物はないです。
まずまず知らない用語多すぎて調べていたらキリがない状態です。
とりあえずハンズオンな雰囲気のページを見つけて、実際に必要な作業を試してみました。
ですが、大前提となる目的やリスト化してどの様に運用していくか？などをかっ飛ばした状態でやってみても意味不明でお姉さんに頼りました。　
お姉さんも「意味不明💦これ読んで誰がわかると思ってんだ💢」と言いながらも解読していただき、認識が合っているか？試した作業が成功しているか？の確認をしていただきました。

3.手順書の作成

私は今までqiitaでご紹介してきたように初心者目線で手順を書いてきました。
ですが歴戦の猛者のようなSEさん達にどのように書けば良いかわからずとても悩みました。
現場で見かける手順書は短い走り書きのようなもので、それを元に業務にあたっているのを見ていました。
長々と書くのは良くないかもしれないと思ったので、メモのような下書きを作り、お姉さんに添削して貰ったのですが、雑すぎて分厚い資料読んだ方が良いと酷評されました💦
動作と動作の間が全然わかんないよ！！と言われ、あれだけ嫌っていた暗黙の了解を自分で作っていたのです。
私は慣れている人にどれだけ情報を提供したら良いかがよくわからず、色々書きすぎて簡潔でないといけないと考えすぎていました。
お姉さん曰く、「どんなに経験があってもわからないものはわかんないし、皆さん読めているようで読めてなくて、聞きに行っているし、誰も丁寧に書かない怠け者なだけやから！！」となんとも言えない意見をいただき、qiitaのように書くことにしました。

手順書作成で心がけたこと

1. 読み手の状況を考えた文章
   皆さん常に何か別の作業をしながら別の作業をしてます。
   なので片手間で出来るように難しい言葉は使わない、小学生でも読めるようにしました。
   簡潔にこの作業の目的、実施期限、格納先とファイルの命名規則を提示して頭を使う必要を無くします。

2. ステップバイステップの構成
   手順書は、誰が見ても分かりやすいステップバイステップで構成することは当然だと思いますが、各手順を明確にして、自分でやってみた時のスクリーンショットも加えました。これにより視覚的にも理解しやすくなります。

3. 環境・前提条件別に作成
   皆さん超多忙なので、各環境•前提条件別に作成しました。
   自分の使用してるOSや機器のページを目次から探す手間を省くため、初めから分けて作りました。

4. エラー処理の考慮
   手順通りに進めていくと、必ずといっていいほどエラーに直面します。
   エラーについての対処法を手順書に組み込み、あらかじめ解決策を提示することで、SEさんの手間を軽減しました。

手順書以外でやった工夫

格納先には予め私が作った完成形を置いておいてわかりやすくする。
忘れてそうな人、忘れられている対象機器を探して実施をお願いする。
数百台ある機器の場所をリスト化して、近くに居る人に実施してもらえるように朝のミーティングで告知。

やってみての感想とフィードバック

無事エラーもなく、2日で集まりました。
遠隔地にいる方々もスムーズに実施していただけたので初めて作った割には良くできたんじゃないかと思います。
手順書を使っていただいた方からは読みやすいくて全く問題なかったと言われました。
集まったものの機器情報の集計して登録する作業が大変で、たまたま来ていたVBA仙人のシニアマネージャーの方に手伝っていただけました。VBAをマスターしようと思います
もっと視野広げないといけないと思ったのが、別フロアでも同じ登録作業をしていて、わからないことを聞きに行けば良かったと思いました。
あとこの手順書作った後にchatAIが導入されました（遅い）
資料のPDFを飲ませると要約してくれるそうでこれあったら大分早く作業が終わった気がします。。。

まとめ

この業務での収穫は経験に問わず暗黙の了解は良くない、と言う事です。
研修の時から手順書の暗黙の了解が気になってしかたなかった私は気になるのは私だけだと思っていました。
暗黙の了解が当たり前の環境だと覚悟していましたが、実際はベテランの人でも暗黙の了解に悩んでいて、言葉が足りないところを解消するために聞いているという状況です。
ミーティングでも言葉が足りなくて解釈違いを起こして、言葉が足りなかったことを謝っているところは何度も見ました。
IT業界誌を執筆している詩人の知り合いは、その言葉から言葉以上のものが読み取れるのが詩や小説で、現場の手順書や取説は言葉以上のものが読み取れないもの、と定義していました。
読書が好きな私はなんでこんなに手順書が読めないんだろうと悩みましたが、つまらなくて当然です。
その言葉以上のものを読み取ろうとしてもしょうがないし、その言葉以上のものが読み取れないものを作成するのならば、言葉をたくさん並べても何一つ悪いことはないと思いました。
そんなに投稿してませんが、qiitaを細々書いていたのは意外と力になっていたのだと思います。
私は人と会話するより、文章を認める方が性に合っています。
エンジニアは文章コミュニケーションは多いですし、これは自分の強みなので細々と投稿していきます。
ここまで読んでくださり、ありがとうございました！