本書は経験に長けた執筆者たちがドキュメントを作成する方法をゼロから説明するフィールドガイドです。
架空のソフトウェア開発チームのストーリーを追いながら、ソフトウェア開発ライフサイクルの各ステップにおいて、ユーザーニーズの理解、開発者に役立つドキュメントの作成、公開、測定、保守に至るまで、開発を最適化するためのドキュメント作成の技術を解説しています。
これまで学ぶ機会のなかったREADME、APIリファレンス、チュートリアル、コンセプトドキュメント、リリースノートなど、さまざまな種類のドキュメントの書き方について学ぶことができる一冊です。
ということで、自分なりに赤線を引っ張った部分のまとめです。
要点
- 良い開発者は単にコピーする。優れた開発者は考えてペーストする。
- ユーザーを理解する方法
- ユーザーのゴールを特定する。
- ユーザーを理解する。
- ユーザーのニーズを理解し、ドキュメントがそれをどう解決するか理解する。
- 分かったことをペルソナ、ストーリー、マップにまとめる。
- フリクションログを使って仮説検証する。
- プロダクトのユーザーのゴールを決めたら、書き留めておく。あとからドキュメントによってゴールをどの程度達成していたか確認することで、ドキュメントの成功度を測定できる。
- すべてのユーザーが同じではない。全員のニーズを満たすのは無理。ビジネスやプロダクトに最も重要なユーザーを優先する。
- 大事なのはユーザーの「ニーズ」に焦点を当てること。「ウォンツ」ではない。たとえば、近くの街へ旅行する移動手段について、誰かに質問するとき、世界中のあらゆる選択肢から選べるなら「スポーツカーでドライブしたい」と答えるかもしれない。しかしかといって、本当にスポーツカーで旅行したいか？
- 初心者のためのユーザージャーニーマップの使い方
- プロダクトクリエーターは「人々がプロダクトを実際にどのように使っているのか」といった本質的な問いに答えなくてはならない。 そのためには、ユーザーの視点からユーザー体験全体の本質を理解する必要がある。
- 執筆で最も難しいことは、白紙のドキュメントに向き合うことである。コードに関してはよく分かっているだろうが、他の人が理解できるように、考えを明確で簡潔な言葉にするのは、精神的にも感情的にも難しい。その難しさを認めることが、ドキュメントを書き始める前の最初の手順である。
- ドキュメントの「読み手」「目的」「コンテンツパターン」から、ドキュメントのタイトルを決定する。タイトルはユーザーから見たドキュメントの目的を、いちばん短くかつ明確にいい換えたフレーズにする。
- アウトライン
- 追記すべき事前情報や設定情報はあるか。
- 飛ばしている手順や、説明が不完全な手順はないか。
- 手順は合理的な順で並んでいるか。
- 見出し
- できる限り、簡潔・明確・具体的にする。読み手が見出しをざっと読めば、ドキュメントの内容を大まかに理解できるようにする。
- 最も重要な情報から始める。読み手に最も重要な情報をできるだけページの一番上に書く。
- 各セクションで重複のない見出しを使う。
- 研究結果によれば、読み手がコンテンツのページを流し読むときの典型的なパターンは「F」の型になる。ドキュメントの上部にあるタイトルとサブタイトルを横２列の向きで読んでから、ページの下に向かって読んでいく。読み手はページの内容を一言一句読んでいるわけではない。
- ポイント
- 大見出しはドキュメントのゴールを要約しているか。
- 複数の見出しによって要約しているか。
- ドラフトは読み手のニーズに応えているか。
- 情報の流れは読み手に理解しやすいか。
- フリクションログで見つけた課題を解決しているか。
- テンプレートに従っているか。
- 手順が動作することをテストしたか。
- できるだけ明確になっているか
- 一貫して使われていない用語で、訂正が必要な用語はあるか。
- 削除してもよい、不要な単語や表現はあるか。
- 読み手が戸惑うような熟語・比喩・スラングはあるか。
- 避けるべき偏った言葉は使われていないか。
- 「サンプルコードの長さは、初期設定のスクリーン幅に収まるような短さに保ちましょう。水平方向へのスクロールバーはかっこ悪いです！」
- スクリーンショット
- 文章中からの参照もしくは説明と一緒に表示されること。
- 説明や関連する文章の近くで表示されること。
- きれいで散らかっていないこと、UI以外をスクリーンショットに含めないこと。
- 読み手が正しい画面で安心できるように、十分な背景情報とともにUIの関連部分が含まれていること。
- 確認
- 正しい順序で並んだ見出しによりトピックが分解されている。
- タスクの時系列で並んでいる見出しがあり期待結果が記されている。
- プロセス中の各ステップの結果が明確である。
- 理解しやすい方法で構成されている。
- 行き詰まりやすい場所を指摘している。
- 遭遇するかもしれないエラー定義が載っている。
- 最終的にはユーザーのコンテンツに対する期待は次のようになります。
- 一貫している：馴染みのある構造とパターンでコンテンツが構成されている。
- 関連している：ユーザーニーズを満たすコンテンツを簡単に見つけられる。
- 見つけやすくなっている：検索して簡単にコンテンツにアクセスできる。
関連
以上です～