【書評】エンジニアのためのドキュメントライティング
なぜ読んだか？
ポッドキャスト「fukabori.fm」の人が翻訳したようで、番組で宣伝してた
宣伝を聞いて「いつもドキュメントを自己流で書いてるなぁ」と気付いた
ドキュメントを書く技術はこの先も役立ちそう！と思い、読むことにした
自分がドキュメントを書く場面
株式会社ゆめみでAndroidアプリエンジニアとして働いているが、主に開発者向けにドキュメントを書くことが多い。
仕様書やツールの説明書など、内部向けのドキュメントの作成がメインなので、同じアプリ開発メンバー宛を想定して読んでみた。
個人的に面白かったところ３選
ドキュメントは機能の１つ
ドキュメントの途中で出てくるリンクは読み手の注意を逸らす可能性がある
読み手はおそらくドキュメントを流し読みするため、最も重要な情報を最初に書く
1. ドキュメントは機能の１つ
この一言に尽きる。
問題が起きた時、最初にドキュメントを探すため、もはや機能の１つと言ってもいい。
ドキュメントがあれば時間を大幅に節約できるし、複雑なシステムになればなるほどコードは完璧にならない。
もっとドキュメントに投資するべき！
2. ドキュメントの途中で出てくるリンクは読み手の注意を逸らす可能性がある
これは自分がよくやりがち。
「とりあえず関係ありそうなリンクをたくさん載せたろ」とベタベタ貼り付けるのだが、これはNGらしい。
なぜなら、リンクが多すぎるとユーザーの気が散るため。
最下部に記載するのがよい、とのこと。
3. 読み手はおそらくドキュメントを流し読みするため、最も重要な情報を最初に書く
読み手は主にタイトルと見出しを読んでいくため、最初の３段落に重要な情報を載せておく。
また、手順書を書いてるのであれば、ドキュメント末尾時点で達成できていることを伝えること。
最後に
今まで作成してきたドキュメントは自分でなんとなくな自己流で書いてきた。
この本を読むことで、読みやすいドキュメントが書けそう。
また、「ドキュメントは全部読まれるもの」という思い込みは間違いのようだ。
確かに、自分もドキュメントを読む時は探している部分しか読んでないかも。。。
まだ全部理解できていないし、読みたい部分しか読んでいないので、ちゃんと読んでいきたい