Alphabetのテクニカルライター、Stripeのテクニカルライターなど、開発者向けドキュメント作成の経験に長けた方々が著者として名を連ねる、開発者向けドキュメントについて書かれた書籍『エンジニアのためのドキュメントライティング』を読んだので感想メモです。

Chapter1 読み手の理解

• Chapter1が「読み手の理解」から始まっているのがとても良い

• 🐮「知識の呪い」初めて聞いた言葉だけど、身に覚えがある

  • 当然だと思っていたことが、読み手にとっては理解できないことはよくある

  • 自分が知っていることが当たり前だと思わないこと

• ユーザーストーリーは実際の利用者と一緒に作るの良さそう

  • または、テクニカルライターは、どちらかというと利用者よりの意識でプロダクトを利用するのが良いかも

• フリクションログ、全ての動作確認において残しておくの大事

  • （フリクションとは摩擦や抵抗のことで、フリクションログとは、ソフトウェアを試して体験した記録を残したログのこと）

Chapter2 ドキュメントの計画

• ドキュメントサイトに必要なメニュー（チュートリアル、リファレンスなど）がまとまっていて、ドキュメントサイトに何を書くか迷っている人はこの章を見ると網羅できる

Chapter3 ドキュメントのドラフト

• まずは書いてみよう、の章

• ツール選びは重要だが、そこまでこだわらずに。使い慣れたツールが一番良い

• ドキュメントのタイトルは、ドキュメントを読むことで達成できるゴールにすること

  • 🐮いきなり書き始めるのではなく、アウトラインから書こうというのは超同意

• 書き方として「タイトル」のつけるタイミング、「リスト」はどのような時に利用するか、「コールアウト」って何？のような基本的なことがまとまっていてとても丁寧

  • 🐮テンプレート化することは統一感を持てるので良い面もあるが、テンプレートにとらわれないようにすることも大事だと思う

Chapter4 ドキュメントの編集

• ドラフトを書いた後のドキュメント肉付けの具体的な方法について書かれている

• レビューには、セルフレビュー、ピアレビュー、テクニカルレビューなどのプロセスが必要

• ドキュメントの編集はコードのテスト・リファクタリングと同様だよ！

Chapter5 サンプルコードの組み込み

• サンプルコードがなぜ必要か、良いサンプルコードとは何か

  • 🐮私もよくサンプルコードを探します。コピーして最小限の修正だけで進められるのがベストだと思ってます。

Chapter6 ビジュアルコンテンツの追加 

• 文章を読むよりビジュアルで見せた方が伝わることもあるよね

• でも絵を描くのは難しいし、アクセシビリティの問題もある

• UIを見てもらうなら、スクリーンショットは有効

• 「文章はすぐ時代遅れになりますが、画像はさらに早く時代遅れになります」

  • 🐮画像の場合だと更新のコストも高いので、時代遅れになるのが容易に想像できますね。。

• とはいえビジュアルの良い点はたくさんあるので、使いたい時は下記に注意して使うこと

  • 理解容易性：読み手に役たつか

  • アクセシビリティ：読み手を限定していないか

  • パフォーマンス：コンテンツサイズ・フォーマットによって読み手は助かっているか？もしくは邪魔されていないか？

Chapter7 ドキュメントの公開

• ドキュメント公開までの道筋について

• 公開までのやることリスト、関係者の洗い出し、公開場所など決めないと

• 公開したらお知らせしよう（じゃないと誰も気づかない）

Chapter8 フィードバックの収集と組み込み

• ドキュメントのフィードバックの集め方

  • 🐮フィードバックを集める手法をさまざままとめてくれているのが助かる。

• フィードバックの優先順位をつける

  • 🐮フィードバックもらった内容を全て対応するとなると工数が、、、となるので、プロダクトのあるべきと合わせて何をやるべきかを考えると良さそう

Chapter9 ドキュメントの品質測定

• ドキュメントの良し悪しどう決めるか

• そもそもドキュメントの品質とは何？から

  • 🐮「機能品質」「構造品質」は、ざっくりとは認識していたが、言語化されるとスッキリする

• TTHW(Time to Hello World): 新しい開発言語を使う開発者が、Hello World を出力させるまでにかかる時間のこと

  • 🐮この測定の仕方面白いと思ったし取り入れたい

Chapter10 ドキュメントの構成

• サイト構成、Information Architect のはなし

  • 🐮超明快 Webユーザビリティの内容が役にたつ

• サイト設計系の話だが、ドキュメントサイトに携わる人は読んでいてそんない内容

• 🐮「書く」だけでなく、「届ける」ところまでフォーカスしているのが良い

Chapter11 ドキュメントの保守と非推奨化

• ドキュメントはリリースして終わりではなく、保守してアップデートしていくのが大切

  • なんとも耳が痛い話、、、書くのはいいが、保守ができていないというプロジェクトには何度も出会ってきたので

• 「ドキュメントオーナーを決める」というのが当然だが大事だと思った

  • 「みんなでやろう」だと絶対にやらないので、オーナーを決めるのが大事。（そしてあなたがオーナーになるべき！）

• ある程度自動化することも大切

• 不要なドキュメントはどんどん削除していこう

  • 残しておくほうがユーザのためにならない

付録

• ドキュメントのプロジェクトを進めるのに参考になるツールやサイトを紹介されています

  • 🐮知らないツールやコミュニティがあるので早速確認しよう

以上です。

私自身、ここ3年ほどは開発者向けドキュメントサイトについて悩んでいるので、かなりヒントをもらえました。
とくに、「Chapter 8 フィードバックの収集と組み込み」「Chapter9 ドキュメントの品質測定」は何度も読み返すと思います。

ドキュメントの大切さだけではなく、書くことの難しさをしっかり書いているとことが印象的でした。
ドキュメント、時間さえあれば書けると思っている方が結構いる印象なのですが、実は必要なのは時間だけではなく、ちょっとしたテクニックだったりするので。

内容気になる方はぜひ読んでみてください。