エンジニアが一生困らないドキュメント作成の基本

はじめに

去年のエンジニア大賞にノミノートされており、気になったので読んでみました！
自己流で記載してきたエンジニアにとって間違えなく一生使えるものだったので、その感想を書いていこうと思います！

ドキュメントの重要性

エンジニアにとってドキュメントを記載する目的は下記3つです。

• 概念や手順を説明する（説明型）
• 知見や活動を報告する（報告型）
• 意見や提案を伝え、相手の行動を促す（説得型）

ドキュメントはプロジェクトの成功に不可欠であり、情報の共有や保守に役立ちます。
適切なドキュメントがあれば、新しいメンバーがプロジェクトにすぐに馴染むことができる。

読み手を意識した書き方

読み手の視点を考慮し、分かりやすく簡潔に書くことが重要。専門用語は必要最低限にし、可能な限りシンプルな言葉で説明することが求められる。また、図や表を活用して視覚的に情報を伝えることも効果的。

文章構成・骨組み

論理的な構成を考えることで、情報が整理され、読み手にとって理解しやすくなる。章や節ごとに内容を分け、見出しを付けることで、読みやすさを向上させる。さらに、目次や索引を活用して、必要な情報にすぐにアクセスできるようにする。

感想

• ドキュメントの書き方を各STEP毎に分けて解説してあり非常に読みやすい本でした。
• なんとなくドキュメントを書こう〜で始めるのではなく、事前に目的・企画をして設計に落として実装する手順はドキュメントでも一緒なので、そこはプログラミングの考え方と変わらないと思った。
• 技術記事やブログでも使えそうだと思った。