訳者である岩瀬さんのツイートをたまたま拝見し、ちょうど先月入社した会社の部署で大きな課題だと感じていたところだったので、購入して斜め読みした。

本書の対象者は、ドキュメントを書くエンジニアやテクニカルライターではあるけど、ユーザー向けドキュメントのようにある程度の規模が想定されているように思う。

私が感じた課題はもっと原始的で、GitHub リポジトリに README.md がなく、どのような README.md を書けば良いか伝える方法を模索していたので、本書がど真ん中だったわけではなかった。

※ 今は、既存ドキュメントへのリンクを張るくらいで良いので、まずは README.md を作るようにチームメンバーなどに伝えている。でもその先が難しい…。

ただ、最後の付録Bに出てきた「README チェックリスト」はチームメンバーへの説明のヒントになるかもしれない。良さそう。

ちなみに自分がドキュメントを作る時はこんな流れ。これでは伝わらない。😅

  1. 概要や書きたいことをとりあえず書いてみて、あれこれ並べる
  2. やっているうちに見出しが見えてくるので、文書構造を作っていく
    • 文書自体はできるだけリストではなく、パラグラフ記法 [2021-11-29-1] を使います
  3. 詳細化したり、逆にバッサリ削除して、完成に近づけていく

読み手目線で書くだけではあるのだけど、それが難しいのだよね。書いたその日じゃなくて、次の日の少し冷静になった頭でもう一度読むなどの細かいテクニックはあるのだけど。

ドキュメントライティングに課題を感じている人は、何かのヒントになるかもしれないので読むと良いかも。

ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング amazon.co.jp