【感想・ネタバレ】ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティングのレビュー

ジャレッド・バーティ / ザッカリー・サラ・コーライセン / ジェン・ランボーン / デービッド・ヌーニェス / ハイディ・ウォーターハウス / 岩瀬義昌

【内容紹介】
「ドキュメントを書いておけばよかった」

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

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

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

ドキュメントを作成している現場のエンジニアやテクニカルライター、プロダクトマネジャーの方に最適の内容です。

【目次】
PART I ドキュメント作成の準備
CHAPTER 1 読み手の理解
CHAPTER 2 ドキュメントの計画

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

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

[ブクログ · ★★★★★]

多くの人は本書を
「わかってる」
というだろうが多くの人がこれをわかっていたらわかりにくい文書や文書のないプログラムは世の中に溢れていない

[ブクログ · ★★★★★]

どうしても後手にまわりがちなドキュメント作成。その重要性を訴え、エンジニアの業務から地続きのところでのHowを描き、運用時に発生する課題までをカバーした一冊。
これ一冊読み合わせるだけでチームのドキュメントの質が劇的に改善しそう。

[ブクログ · ★★★★☆]

　ユーザマニュアルの書き方の解説であるが、他の本と一味違うのは公開、フィードバック、メンテナンスまで扱っていること。ドキュメントは多くの場合、作りっぱなしになってしまうが、そうならないようにするにはどうすればよいかというところにまで配慮が行き届いている。作りっぱなしの問題はすでに起きているので対処法は非常に参考になった。また、ドキュメントの管理もプログラムと同様のバージョン管理システムを用いたりするなどプログラマの視点での解説となっており、プログラマとしては非常に理解しやすかった。そして、この解説自体が解説通りの書き方となっており、具体的のどうすればよいのか？にも答えている。ドキュメントの管理もソフト開発と同様にチームで対応する必要があるが個人でできる部分も多々あるので本書を参考に少しずつであっても対応してきたいものだ。

[ブクログ · ★★★★☆]

ドキュメントはあるけど散在していてまとまりがない、そもそもドキュメントってどう作ればいいのか、ドキュメントを作ったけどメンテはどうするべき？みたいな疑問を持ってる人向け。書き方というよりドキュメントの構築〜保守までのやり方が体系的にまとまっている。ドキュメントに携わる人は読むと何かしら学びがあると思う。

惜しむらくは文章の誤字脱字、てにをはの誤用が何箇所か散見されること。一応ライティングに絡む本なのでそのあたりちゃんとしてほしかった…。

[ブクログ · ★★★★☆]

エンジニアによるドキュメント作成（ユーザーガイド、運用手順書、APIリファレンス、設計書など）について、架空のプロジェクトを例にして順を追って解説されている。
ドキュメントの種類・書き方・考え方の概念的な方法論や教訓が、ある程度高いカバー率で網羅されている。基礎的な知識・原理を身につけることで長い目で見て役に立つ知識を得られるものであり、これを読んですぐにそのままマネすれば良い、というものではないと思う。
実務でエンジニアがやりがちな失敗や「考えが及んでいなかった」というケースへの言及が多く、経験者としては耳が痛いし、それゆえに学びが多い。
文量が多くて時間がかかりそうだったため、全体的に見出し・太文字を中心に飛ばし読みをしたが、それでも十分に学びがあった。もし見出しだけで著者の意図や根拠を読み取れない・納得できない場合には本文を熟読すると良いだろう。また後で時間があるときに本文の熟読をしたいという読後感を持った。

42ページ
ユーザージャーニーマップ
→作り手はユーザー体験を考慮しないことが多い。あるいは考慮しようとしているのに考慮できていないということも多い。利用者や読み手に優しくないモノを生産しがちなので、この問題に対する答えのひとつがユーザージャーニーマップなのだと思う（本文を読んでいないのでこの解釈で合っているかは自信がない）。

56ページ
・できるだけガイド単体で読めるようにしましょう。ユーザーが必要とするすべての行動を1つのページにまとめておきましょう。
→これは本当にそのとおりで、ほかのページと行ったり来たりすることの煩雑さを考慮するべき。できればリンクを飛ばずに単体で完結するほうが最も望ましいが、構成次第ではやむをえずリンクをつけて往復させることもあるだろう。また、たとえばWikiとファイルサーバのように異なるプラットフォーム上で往復させることも避けるべき。リンクを貼ること自体はやっても構わないが、リンク先の概要・サマリー表やスクリーンショットなどをリンク元に貼るようにしたい。

83ページ
最も重要な情報を冒頭で述べる
→これも本当にその通りで、できていない人が多い。仕事においては「起承転結」よりもPREP法（POINT→REASON→EXAMPLE→POINT）を使いましょう。ストック的なドキュメントだけでなく、メールやメッセージでも結論を先に書きましょう。長々と何行も文を書くときに下から2行目くらいに結論を書くのはやめてほしい。

177ページ
タイトルと最初の段落の両方に、ドキュメントの目的と、読み手が達成できることを書いておきましょう。
→やるべき。考えなしに作ると省きがちだが、読み手はまずそのドキュメントの位置付けを理解してから内容を読まないと正しく解釈できないので、位置付けや意義を早い段階でわかるように作るべき。

[ブクログ · ★★★★☆]

流し読み。ドキュメントの構造に心を砕きたい。
社内ドキュメントを書く機会が増えているので参考にします。