先日パソコンのデータが紛失してしまい、バックアップをとっていないデータが、かなり無くなってしまいました。今までGitHubに公開せずに利用していたコードなどもなくなってしまい、1から調べなおさないとコードが書けなくなりました。まだ、分かりやすく書かれているサイトや動画はときはいいのですが、自分が書いたコードが使いたい場面も多いです。
バックアップをしっかりしていなかったことをものすごく後悔しました。そこで、今一度、自分が見ても、分かるようにWEB上に自分のコードや調べたことをまとめる必要があると思いました。よくエンジニアに言われる「アウトプットが大事」「他人が見ても分かるよう書く」ことが、本当に大事だということに改めて気づかされました。
実際書き始めるにあたって、参考にするものとしては、マニュアル、手順書、レシピなどです。これらの書き方やルールについてまとめようと思います。
今回の調べ方としては「マニュアル 書き方 コツ」で検索して、ヒットした動画を上から3本見たものの内容から生かせそうなものをピックアップしました。
ちなみに一番参考にしたサイトは以下のURLの動画です。
https://www.youtube.com/watch?v=qLFjwtMpBbE
3つの動画に共通して最初に説明があったことは、「マニュアル作成を行う目的をはっきりさせる」ということです。例えば新人のアルバイトに教える時間を短縮することや部下に業務の引継ぎがしやすくなるなど様々な目的があります。今回の場合は「久しぶりの時や初見の人でも再現が取れるように書く」ということが目的だと思っています。
そのためには、見る人が変わる前提で設計されているべきです。使う言葉や図も誰が見ても分かるように共通したもの、自分の記事を引用やコピペされたとしても、理解できるようにまとめる必要があると考えました。また、一回で完成させるのではなく、改定や改正を前提に作成していくということです。Web上でよく見られる最終更新日のようなものも記載するようにしたいと思います。
具体的なルールとしては、まず三つ考えています。
1概要と詳細を記載すること
2画像や図を入れること
3穴埋め形式でパターン化すること
タイトルは「WEB×マニュアル×書き方」
概要では、1前提知識、2材料、3全体の目次、4目的、5日付、6文字量、７読む時間などを記載しましょう。
今回の場合
1、特になし ２，メモ帳、ペイント、Twitter、Qiita垢 ３，詳細7つ ４，マニュアルの型作成 5、22/11/07（1回目） 6、1600字 7、5分
詳細では、図のように一つ一つスクリーンショットやコードの変化が分かるように、すべてに画像を乗せておくべきだと考えました。
1、情報を集める
2、情報をまとめる
3、図を用意する
4、文章で説明する
5、推敲
6、公開
7、反省
１、Webでの検索方法とブックマークのＵＲＬを記載して、上から3つぐらいをコピペして知識を蓄えます。約30分はかかると思います。
2、紙に箇条書きなどでまとめるほうがいいです。色をつけたり分類分けしたり色々試してみたいと思います。個人的にはここが一番重要だと考えています。
3、必要がある画像の数を先に決める（7工程以下）にするというルールを継続してみたいと思います。これをオーバーする場合は記載する工程で省くか、別のレシピやマニュアルを参照してくださいという方法で別のページ上に誘導することをおすすめします。
４、誰が見ても分かるように図やコードに解説を入れましょう。
５、コツコツと
６、積み重ねて
７、繰り返して
まとめでは、最終的な結論をはっきりと述べるようにしましょう。
1概要と詳細を記載すること
2画像や図を入れること
3穴埋め形式でパターン化すること
の3つがマニュアル作成では大切だと考え実践してみましたが、１は詳細がハッキリとしていないと感じました。テーマにもよりますが、「水100mlを入れ中火で５分加熱」ぐらい具体的に書けるようにしたいです。２の図に関しても時間がかかりすぎないように効率よく準備できるツールや方法を見つけたいです。３に関してはコツコツと積み重ねて繰り返して、練習してパターンが見つかると信じています。
感想や反省も適当に書きましょう。
結論・・・読みづらすぎるので、他の人が書いた参考になるサイトやマニュアルから勉強してください。