ドキュメント作成の基本を読んで

読もうと思った理由

次の転職先で、最初の半年はドキュメントの作成やレビューをすることが決まっている。
そのため、今まで見よう見まねで書いていたドキュメンを
作成する意図から書き方まで体系的に学べる書籍はないかと思い
この本に辿り着いた

読んでみた感想

実際に読み始める前に、自分の師である人に言われたが
書き方はわかるかもしれないが、書く内容は多分わからないだろう。ということ。

実際にそうだった。
伝わりやすい構成を知る。ということはできたので満足であるが
じゃ、明日から書けるかというと
ソフトウェアを開発する人として、どんな内容を書けばいいかは
まだわからない。

この辺りは、技術力が高まり、1人称で開発できるようになって
初めて書けるようになる部分だと思う。

だからこそ、今後
1人称で開発ができるようになった時、リーダーになった時
など、できることが増え、レイヤーが上がった時に
読み返したいと思える本だった。

実際に勉強になったところ

ブログを書いている人にとっては当たり前かもしれないが
まず、骨組みを作るところ。は自分がドキュメント作っている時に視点はなかった。
また、ある程度読み飛ばす人がいる。という想定もなかったので
読者の想定をちゃんと定義して、ドキュメントを作ろうと思った。

読んだ、当日に後輩のドキュメントをレビューをする時間があった。

その時に
・想定読者(〇〇会社のエンジニア経験⭕️年目だがこのシステムにはかかわっったことがない)
・前回、システムの資料を作成したが読み飛ばしている可能性もあるので紐付ける
などなど

本を読んだことで得た『視点』を使って
レビューしたところ、こんなこと考えてるんですね！
と、いい反応をしてくれた。嬉しかった。

ただ、このレビューは俺だったらこう書く。ってだけで
後輩くんが不要と思ったら、やり直さなくていいよ。
と言ったら、ほぼそのままで提出していた。

いいドキュメントを作る方法と、後輩くんに納得させドキュメントを直させる方法
はまた、別の話みたいです。
ひび精進していきます。