エンジニアのためのドキュメントライティング(エンジニアノタメノドキュメントライティング)

「ドキュメントを書いておけばよかった」

開発者であれば一度は思ったことがあるかもしれません。

ドキュメントは開発側の生産性とユーザーの利便性を高めるものです。
さらに言うと、ドキュメントがなければ、ユーザーに使われる機会が確実に減ります。
開発者がいかにすばらしいプロダクトを作ろうが、ドキュメントの欠如がその価値を奪うのです。

本書は経験に長けた執筆者たちがドキュメントを作成する方法をゼロから説明するフィールドガイドです。
架空のソフトウェア開発チームのストーリーを追いながら、ソフトウェア開発ライフサイクルの各ステップにおいて、ユーザーニーズの理解、開発者に役立つドキュメントの作成、公開、測定、保守に至るまで、開発を最適化するためのドキュメント作成の技術を解説しています。
これまで学ぶ機会のなかった README 、 API リファレンス、チュートリアル、コンセプトドキュメント、リリースノートなど、さまざまな種類のドキュメントの書き方について学ぶことができる一冊です。

ドキュメントを作成している現場のエンジニアやテクニカルライター、プロダクトマネジャーの方に最適の内容です。
PART I ドキュメント作成の準備
CHAPTER 1 読み手の理解
CHAPTER 2 ドキュメントの計画

PART2 ドキュメントの作成
CHAPTER 3 ドキュメントのドラフト
CHAPTER 4 ドキュメントの編集
CHAPTER 5 サンプルコードの組み込み
CHAPTER 6 ビジュアルコンテンツの追加

PART3 ドキュメントの公開と運用
CHAPTER 7 ドキュメントの公開
CHAPTER 8 フィードバックの収集と組み込み
CHAPTER 9 ドキュメントの品質測定
CHAPTER 10 ドキュメントの構成
CHAPTER 11 ドキュメントの保守と非推奨化

コードは書けるのにドキュメントになると手が止まる。あるいは書いたものが読まれない。エンジニアがドキュメントに苦手意識を持つ背景には、「何をどの順番でどこまで書けばよいか」の方法論が存在しないまま作業に投げ込まれる構造的な問題があります。本書は Google や Stripe で開発者向けドキュメントを手がけてきた著者陣 (Jared Bhatti ら) が、その方法論を一冊にまとめたものです。原著 "Docs for Developers" の日本語版にあたります。

読者の分析、ドキュメントの種類 (チュートリアル、リファレンス、概念説明など) ごとの設計原則、ドラフトからレビュー・公開・保守に至るライフサイクルの回し方まで、ドキュメント制作の全工程をカバーします。架空の開発チームが製品ドキュメントを立ち上げていくストーリーを通じて学ぶ構成のため、抽象論で終わらず具体的な判断場面に落とし込まれています。

テクニカルライター専業の人だけでなく、 README や API ドキュメントを書く機会のある開発者、 OSS のコントリビュータ、プロダクトマネージャーに広く役立ちます。文章力の鍛え方というよりも「ドキュメントを設計する力」を養う本であり、書く前の段階で迷いを減らしてくれます。