開発の手順や、バグの解消手順などをよくブログにまとめています。
これを書く作業って、実はちょいと面倒くさいのだ( ˘ω˘ )

でも、面倒がって執筆を後回しにしていると、いざ書こうと思った時には、もう作業の手順を思い出せなくなっていることがしばしば。

ということで、サクサク開発手順をまとめるための自分なりのコツについて書いてみます。



ドキュメントを書く流れ



行き詰まった瞬間に「これはネタ」と考える

作業中に行き詰まったり、バグが発生した瞬間に、
「あ、これは記事（or ドキュメント）にしよう！」
と決めています。

すると、その後の作業をするにあたり、どうわかりやすくまとめて他人（未来の自分を含む）に伝えるか？に意識を向けられるようになります。


キャプチャを撮りながら作業を進める

うまくいかなかったら、その瞬間に、とりあえずエラー文言が出ている画面や、問題が出ているページなどをすぐキャプチャするようにしています。

あれこれ作業した後で、
「あ、解消したはいいけど、うまくいかない場合にどんな表示が出るか、キャプチャを撮っていけばよかったな...」
と後悔することが多いので。

いらないキャプチャなら、後でゴミ箱に捨てればいいだけなので、とりあえずこまめに作業の手順を撮っておきましょう。


メモ（=ドキュメントの下書き）を書きながら作業を進める

作業に夢中になると、まぁ、前後に何をしていたのか忘れます笑
ので、こまめにメモを残しながら進めましょう。

読ませるための綺麗な文章でなくていいので、「何をしたらどうなったか」を、最低限メモっておきます。

後でまとめよう...と思うと、抜け漏れが増えますし、間違いなく面倒くさくなるので、作業しながら、並行でメモを取っていくのがポイントです。



無事解決したら、行き詰まりを再現して、自分のドキュメント通りにやり直す

やった！無事解決！
解決方法も、ステップごとに全部メモ書きできたぞ！

...となったら、わざと同じエラーを発生させ直したり、これまでドキュメントを書きながら組み上げた設定を初期化したりすることがよくあります。

ドMなのではなく、自分の手順書だけを見て、その通りに進めたら、本当にうまくいくか検証するためです。

この手順を踏んで、もしドキュメントに漏れがあったら、追記します。

これにより、更にわかりやすく、正確なドキュメントができるんですね。



まとめ

とりあえず適当なドキュメントでいいか！
と簡単なメモを残しても、数ヶ月後には何もかも忘れていて、ただの暗号文になっている...という経験を何度もしました。えぇ。

そんな経験から、上記の丁寧ドキュメント作成術を編み出したというわけです。


基本的に、ブログで出している技術系の記事は、主に未来の自分のために書いているものです。

が、公開することで、同じ問題に行き詰まる誰かの助けになれば一石二鳥だな、と思っています✌︎('ω'✌︎ )