エンジニアのためのドキュメントライティングという本を読んだのでまとめようと思います。
どういう本か
▶️社内ドキュメントではなく外部のユーザーに向けたドキュメントライティング。
▶️一般ユーザー向けではなく開発者向け(APIの仕様書)などに特化
▶️細かいテクニックではなくドキュメントを各部分から保守する部分までの一連の流れがわかる。
当書の展開としては実際に犬と会話できるサービス(API)を作ったとあるベンチャー企業が開発者向けにドキュメントを公開するまでの話が物語形式で展開される。最初の章は実際にユーザーインタービューから始まり最終的にドキュメントの良し悪し、改善していくところまで描かれており、随時でポイントを説明してくれる。
テック系の本で物語形式は珍しいような気もするが、淡々と説明されるより話に入り込めるので課題と解決策の結びつけがしやすく読みやすかった。
所感
社内のドキュメント不足に課題を感じていたのでこれから増やしていきたいねというフェーズでこの本を読んだ。
目的としては社内のドキュメント拡充、例えば「ドキュメント文化の始め方」とか「どういうフォーマットが可読性が高いか」とか「ドキュメントの劣化への向き合い方」みたいなところが知りたかった。しかし、当書のコンセプトとしてはどうやら外部へ公開するドキュメントがメインの話となっており自分の目的とはややずれていた。
とはいえ、この本自体は開発者向けのドキュメントを書くにはすごく丁寧でわかりやすく説明してくれていて、自分でOSS出したりAPIを外部公開するなどの機会があればもう一度読むことになりそう。
実際にドキュメントを書いていく章では一般的な文章を書く際にも使えるテクニックが書いてあるので、そのあたりは知りたいことが書いてあった。
また、一般に想定されるユーザーガイドのようなドキュメントだけではなく、コードコメントやREADMEもドキュメントコンテンツとして説明されている。この辺は「エンジニアのための」と謳っているだけあり、なかなか勉強になった。
よかったところをまとめていく
これ良いなと思って線を引いたところをまとめていく。
開発ループを意識する
ドキュメントを書く際は開発時のループを考える必要がある。
開発者は普段以下のループを行なっており、これらのステップを進められるようにドキュメントが必要とされるからである。
- 問題の理解を試みる
- 思いつく場所を全て探して、既存の解決策を探す
- 運良く見つけられたら、その解決策を試す
- 解決策を本番環境にリリースする
ドキュメントを書く際は今開発者がどのステップにいて何を求めているかへの意識が必要である。
フリクションログを取る
良いドキュメントを書くためには読み手の気持ちを理解する必要がある。しかし悲しいこと自分の知っていることと読み手の知っていることのギャップを認識できずに自分よがりな文章を書いてしまう。当書では知識の呪いとして紹介されていた。
知識の呪いを防ぐために、フリクションログを取ることが推奨される。フリクションは「摩擦」という意味であり、時際に自分がドキュメントの手順通りに実行してみてうまくいかなかった(摩擦があった)箇所をメモしていく手法である。
「良いコードは自己文書化されている」の罠
ドキュメントのタイプとしてコードコメントが紹介されているその中での言及があった。
「良いコードは自己文書化されている」というフレーズをよく聞くが誤用されていることが多い。
自分も駆け出し時に読んだ「リーダブルコード」のコメントに関する章を読んで、コードにコメントを書くことは悪という誤った理解をしていた。
正しくは、良い命名・設計・コード・パターンによってコードが理解しやすくなるのは本当で、容易に理解できることをコメントに起こす必要はない。ただし、複雑なロジックでは他の人(未来の自分を含め)が内容をすばやく理解するためのためのコメントは必要である。
さらに、設計上の意思決定やトレードオフ、なぜそうしたかはコードからは読み取れない。
(コメントに Why not を書こうという話も有名である。)
複雑なシステムではコードが完璧になることはないためコードが自己文書化されることは滅多にないという意識を持つ必要がある。理想へ向かうことは大事だが現実に盲目になってはいけない。
READMEのフォーマット
システム全体の概要を理解するためにコード全体のようやくを書く場所。
次のフォーマットがお勧めされていた。
概要(コードが実行していること)
インストール手法
トラブルシューティング手順
コードのメンテナー
ライセンス情報
更新履歴
基本的な例
より詳細な情報やドキュメントへのリンク
リストはよく使われる順に並べる
ドキュメントの書き方のテクニックとして書いてあった。
例えば、対応している音声ファイルの形式を箇条書きリストで表現する際には次のよく使われる順に並べると必要な情報が見つけやすい。アルファベット順でも問題ない。
リストが長くなればなるほど流し読みができなくなるので10個以上のリストは分割を検討する。
コールアウトは文脈に沿わないが知っておくべきことを書く
コールアウトは文脈に沿わない情報を強調したい時に使うことができます。
ドキュメントを書いているときに、その時点で知るべきちょっとした情報ではあるが、コンテンツの流れにそぐわない情報に気づくことがあります。その情報は、読み手の安全を確保するために、絶対に知っておくべき重要なことかもしれませんし、ドキュメントのある時点で強調しておきたいような有益な関連情報かもしれません。そんなときに、コールアウトを使えます。
例として次のようなものが挙げられていた
- 警告: 実行しないでください！危険な状態に陥るかもしれません。
- 注意: ユーザーから許諾を得ている場合にもに API を利用してください。
- ヒント: 今読んでいることに関するヒントを書く。
コールアウトが多いと読み手は疲れるので重要な情報のみに使う。
人間は流し読みをする
実は、読み手はドキュメントの内容をほとんど読んでいません。
探し物が見つかるまで複数のページ、セクションを流し読みして探し物が見つかった時にじっくり読みます。
いわゆる「F」の形に沿って読まれており、ドキュメントの上部にあるタイトルとサブタイトルの2列を読んでから下に向かって読んでいる。
つまり良いドキュメントは流し読みのために次のことが必要条件である。
- ドキュメントのゴールを要約してタイトルに設定する。
- 最初の3段落に重要な情報を載せる
- セクションごとに要約した見出しをつける
編集はユーザーニーズに応えているかを見る
編集はドラフトで作ったアイデアを文法的に見やすくしたり評価するプロセスである。
編集は執筆時とは異なる客観的かつ批判的な観点から見る必要があるため、ドキュメントの作成は執筆(ドラフトの作成)と編集のフェーズに分けるべきであり二つとも同時に行ってはならない。
建設的な追加提案ができるならば、アイデアを批判して良い
フィードバックはコードレビューと同じ。
批判で終わるのではなく、提案によって問題解決につながる追加を行うことが目的です。
フィードバックはより具体的であればあるほど良く、そのために次のことに注意する。
- 人ではなく、アイデアに集中する。
- うまく説明できているものは褒める
- フィードバックへの返答は即時ではなく検討する時間を設ける。
言葉では足りない時は画像を使う
人間の脳は、画像であれば 13 ミリ秒で処理できる。
不要な情報を入れないように UI 以外を含めな異様に注意する。
ただし、画像は更新のコストが高いことは忘れないように。
ドキュメントオーナーを割り当てる。
ドキュメントの責任が全員にあるということは誰も責任を負っていないことである。
責務の明確化のためにドキュメントオーナーを任命しよう。
同時にドキュメントの作成や保守は「余分」や「追加」のタスクではなく業績に組み込まれるべき重要なタスクであることを明示する必要がある。ドキュメントの保守に対する賞賛や報酬をつけ労力に報いることが重要。