『エンジニアのためのドキュメントライティング』を読んだ

とても良い本だったので、書評を書いてみようと思う。

https://amzn.asia/d/5KAf9cv

結果的には、これらの期待は全て満たされていたので、買ってよかった。

問題に直面した時の解決ワークフロー。書籍内では「開発者ループ」と呼んでいる。

このループの中で、わかりやすいドキュメントが存在するかどうかが生産性の観点で重要。しかし、現実ではドキュメントが存在しないケースがよくある。

「書き手のループ」について

フローは、開発者ループと同じで表裏一体。

書籍では、 Corg.ly という架空のペット向けサービスを行う会社のソフトウェアエンジニアが、開発者向けドキュメントがない状態からドキュメントを作成・運用するまでの流れを具体的なユースケースとして説明している。

ユーザーを理解する方法

「知識の呪い」とは、自分が持っている知識・理解を他人も同じように持っていると勘違いしている状態を示す。

例えば自分が、あるシステムに詳しい場合に他のメンバーも自分と同じぐらい詳しいと思い込んで、ドキュメントは不要と思っている状態は、呪われていると言える。

フリクションログというのは、ユーザーが達成したいゴールをプロダクトが提供する機能を使う場合に障壁、良かった点などをログとして残しておくことだと、書籍には説明されている。

文章の流れにそぐわないが、その時点で知るべき情報を入れたいときに使うのが良いらしい。

↓ こういうやつ

そもそも、普段はあまりコールアウトを意識して文章を書いてはいなかったので、これは新鮮だった。

複数の登場人物(アクター)がいる場合にそれぞれが何をするのかを各アクターのレーン毎にフローチャートに図解したものがスイムレーンらしい。水平レーンと垂直レーンを併用して、どのアクターがどんな手順でそれぞれ何をするのかが一覧できるのでこれは役たちそう。

例えば、ドキュメントのPV数が多いからと言ってそれが良いイベントとは限らない。スタートガイドなどのアクセスが多いということはユーザーが増えていることの証左だが、トラブルシューティングやエラーのページのPV数が多い場合は、ユーザーが何かしら問題に直面していることを示す。

ドキュメントにおいてもモニタリングすることは重要だし、社内ドキュメントでもよく参照されるものは分析したほうが良さそう。

テクニカルライティングを学べる無料のコースやテンプレートなどが紹介されていたのはありがたい。

例えば、Googleのテクニカルライティングのコースやテンプレートなどが紹介されていた。

ソフトウェアエンジニアやライターに限らず、だいたいの人は、文章を書いて読んで仕事する必要があるので、万人に薦めたい書籍でした。

個人的に刺さったのは、「テクニカルドキュメントは、小学校高学年程度の読解レベルで書かれている必要がある」 という文章で、常にそれを意識しつつ「知識の呪い」に呪われていないかを自問自答しながら、文章を書こうと思えた良い書籍でした 🙌