こんにちは、虎の穴ラボのシンザキです。

本記事は2023 夏のブログ連載企画の23日目の記事になります。

昨日22日目はgodanさんによる「モダンLinux入門は手元においておきたい一冊だった」が投稿されています。
明日24日目は白石さんによる「とらラボ！×YUMEMI「勉強法の勉強会#2」のイベントレポート」が投稿される予定です。

普段のエンジニアの業務において、「README」や「APIのリファレンス」「リリースノート」など、ドキュメントの作成機会は多々あります。
しかし、私自身ドキュメント作成時に「何から書けば良いのか」また「わかりやすく伝えるためにはどうすれば良いか」と考え込むことが多く作成に時間がかかってしまう悩みがありました。
そこで今回は、エンジニアリングに関するドキュメントの書き方が解説された本がありましたので、本の内容の紹介と読んでみた感想をお伝えします。

基本情報

タイトル	エンジニアのためのドキュメントライティング
著者	ジャレッド・バーティザッカリー・サラ・コーライセンデービッド・ヌーニェスハイディ・ウォーターハウス
訳者	岩瀬義昌
発売日	2023/03/11
出版社	日本能率協会マネジメントセンター

pub.jmam.co.jp

書籍の内容

本書は、全3章で構成されています。PART1では、ドキュメントを作成するにあたって必要な事前準備について解説されています。
PART2では、読みやすいドキュメントの作成方法に焦点を当て、具体的な手法が紹介されています。
最後に、PART3では作成したドキュメントを長期間にわたって効果的に運用するための方法について述べられています。
また本書では、架空のサービス開発を元に、作成例が随所に書かれているので、実務に落とし込む際にもイメージがしやすいです。

良かったところ

タイプ別でドキュメントの基本的な書き方が学べる

「README」や「APIのリファレンス」「リリースノート」「手順書」などエンジニアがよく作成するドキュメントを題材に、各ドキュメントの説明や、必要項目などが解説されています。テンプレートがない状態で、一から作成する場合に、どういった項目が必要か参考になります。

分かりやすく伝えるための手法が書かれている

内容をより分かりやすく伝えるための文章の書き方はもちろん、エンジニアならよく目にする、サンプルコードの組み込み方やフローチャートやデータフローなど、見た目がわかりやすいイメージ図の作成方法も書かれています。
文章だけではなく、見た目の表現するイメージ図の書き方も解説されているのは嬉しいポイントです。この辺りは、LT会でのプレゼン資料の作成に応用が効きそうです。

効率良いドキュメントの作成方法が書かれている

本書では、ドキュメントの基本的な作成方法はもちろん、効率良い作成方法なども解説されています。
中でも「冒頭から書く必要がない」が個人的には参考になりました。
私自身、ドキュメントを作成する際に、冒頭の文章（はじめに）から書くことがありましたが、この冒頭の文章を考えるのに時間がかかって結果、本文の作成になかなか進まない問題がありました。あえて本文を先にざっくりと概要レベルで書いて、本文の内容がある程度固まった状態から冒頭の文章を書く方が書きやすい場合があります。このテクニックはこのブログ記事を作成する上でも、参考になりました。

公開後に行うべきドキュメントの質を上げるための方法も書かれている

これは「よくある質問集」など、お客様（ユーザー）向けに作成したドキュメントの話になるのですが、ドキュメントを公開したあとのフィードバック（アンケート）の収集方法や収集した後の対応法が解説されています。
「Q＆A」ページによくある「この質問は役に立ちましたか」などドキュメントがお客様（読者）にとって有益な情報になっているかアンケートを取る方法や、アンケートから頂いた改善の声を元に、ドキュメントの品質を上げる方法も書かれています。

こんな人におすすめ！

ドキュメントの作成に苦手意識がある方や、作成方法について学びたい方におすすめです！
私自身もドキュメントの作成方法については悩むことが多々ありました。「もっとわかりやすい内容が書きたい！」や「もっと早く文章が書けるようになりたい！」こういったドキュメントに関する悩みの解決のヒントが本書にはあります！

まとめ

作成する前準備から作成方法、公開後のメンテナンスまで、ドキュメントに関する手法が分かりやすく解説された本でした。
伝えたい内容が分かりやすく書かれていて情報も随時更新される、長く愛されるドキュメントにするための方法が書かれています。
ドキュメントの作成に悩む事がありましたら、ぜひ本書の購読をお勧めします！