手順書の手順書（with Markdown AI)

Last updated at 2024-06-26Posted at 2024-06-24

手順書の手順書（with markdownAI)

さいきん、リモートワークが浸透してきて、手順書を書く機会も使う機会も増えてきました。

作業するにつれ、自分の中で、「うれしい手順書」という理想がだんだんと育ってきたので、個人的なメモです。

想定レベル：
作業者は新人のアホであり、これからする作業をぜんぜんやったことはないが、「手順書があるから大丈夫」 と言われた。
ググることはできるが基本的に及び腰であり、「手順書があるから大丈夫」という言葉を先ほどから3回繰り返している。.gitignoreを編集するだけの社内作業であり、おそらくは間違ってもさほど大きなミスにはならない（手順書を作成した人は会議中で、すぐには返事ができない）。

作業の目的
●gitリポジトリの更新作業
●関係者への連絡

これがない場合、よくわかっていない作業者の視野は、びっくりするほど何をしているかわからない作業になります。

自分がやっている手順にフォーカスし、それが成功するか、失敗するかしか見えなくなります。

自分がいま何をしていて、どんな作業をやっているかどうかわからないといざというときに自分でリカバリーするのが難しくなるほか、助力を頼めません。

△ 硬直時間が発生する

nano .gitignore

〇より良い

# .gitignoreの編集
 nano .gitignore

もっと親切に言うと、「.gitignoreを編集して、無視リストに追記して不要なファイルがgitに登録されないようにします」ではありますが、そこまで親切にしなくても、とにかく「.gitignoreを編集」というワードだけでもあると助かります。

慣れている人ならnanoがエディタであることは火を見るよりも明らかですが、nanoを触ったことがない新人はおそらく炎上しています。
nanoの使い方をググりたい。そんなときでも「.gitignoreを編集するために、nanoを使う」というヒントがあればどこへ向かおうとしているのかわかります。

とくにconfigの設定など、一度っきりで済むものには（初回のみ）と書いておきます。
何をしているかわからない側では判断がつかないので、ありがたいです。

△硬直時間が発生する

nano .gitignore

〇あると嬉しい

Jupyter Notebookで以下のコマンドを実行する。

# .gitignoreの編集
nano .gitignore

それはコマンドプロンプトでやっているのか、SSHで接続したコンソール上でやっているのか、書いている側は「わざわざ書かなくても……」というところですが、使う側からするととても大切です。

後から思い出そうとしてもダメなので、メモをする習慣をとっておくといいです。
参考のURLも添えるとより素晴らしいです。

とはいえ、夢中になってると「AがだめでBがだめでCがだめでDがうまくいった」「AかBかCのどれかが良い感じに効いた」みたいなことがでてきます。

自分以外が使用していないドキュメントというのは、校正されていない文章とおんなじです。
できる人はできるんですが、稀で、普通の人は当たり前だと思っているところでつまづきます。

たとえば、最近だとハードウェアの環境をインストールする手順書を展開したら後輩が詰まっていたのですが、そもそもPythonがインストールされていなくて、インストールする必要がありました。
（私の環境にはすでにPythonが存在していたため、意識せずスキップしていた）。

アホなのでこれだけは自信があります。

さいきんはSlackで手順をブツブツつぶやいていると、詳しい人から飛んできていい感じです。

Qiitaでも、ぽんと書いておくと訂正してもらえたりしてありがたいです。

たとえ、ドキュメントを完璧に作り切ったとしても、それは永遠ではなく、UIが変わったり、手順が変わったり、メンテナンスをする必要があります。

手を入れるべきところに手を入れて、手を抜くべきところに手を抜けるといいのですが、抜いてはいけないところで手を抜くとたいへんなことになります。

こういったメモを書いておくには、マークダウン形式が便利です。
マークダウンの良いところは画像を付けられるところで、言葉にすると説明しづらいところが一発でメモできたりします。

これは、せっかくなのでと思って、キャンペーン中の、markdownAIのエディタを使用して書いた記事です。
そちらの使用感については後程、別の記事にまとめたいと思います。