お久しぶりです。先日、皆様のおかげで大学を無事に卒業したなおぽんです！🐹
この度も読了した本をまとめました！
読んだ本
「ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング」
本書の内容
まとめ
ドキュメントの役割
アプリケーションやAPIなど、それらのものを使用する人が正しく使えるように導くことがドキュメントの目的となります。
優れたドキュメントの3C
優れたドキュメントと呼ばれる書類には以下の3Cが大切のようです。
Clear (明確な)
定義がしっかりされており、読み手の不明瞭な点がないことです。 例：- 技術力がどの程度ある人向けのドキュメントなのかが明確である
- 何について書いてあるドキュメント、またはセクションなのかタイトルだけでわかる
- アプリケーションなどの使い方の手順が順番通りである
Concise (簡潔な)
不要な内容が含まれていないことです。例：Ruby on Railsのnewコマンドの説明セクションに、Railsのインストール方法の話を入れない
Consistent (一貫した)
ドキュメントの構造が一貫していることです。例：
- タイトルに沿ったセクションがある
- セクションの説明がある
ドキュメントライティングの仕方
優れたドキュメントの3Cを守りながらライティングを行うには、コードを書きながら並行して以下の方法で執筆することをおすすめだと記されていました。
- そのドキュメントの目的をはっきりさせる
※誰がどんな時に読むドキュメントなのかを明確化 - ユーザーの視点に立ち、何が必要か洗い出す
- ユーザーの意見を調査
- 洗い出しした内容をアウトラインに書き起こす
- 書き起こしたアウトラインをもとに執筆
※必要・不必要な部分を随時追加・削除しながら書いていく - 執筆が終了したらユーザーからのフィードバックをもらいながら随時改良を行なっていく
また現時点で変更される予定があるコードには、注意を促しておくなどがありました。
最後に
ここまでお読みいただき誠にありがとうございました！🐹
個人的には周りくどい書き方が多いなと思いながら読みました笑 ですが、ドキュメントはアプリなどを使用する人が参考にする道標だから軽く見てはいけないということを伝えており、ドキュメントに対しての考えを改めたい方にはおすすめです。