わかりやすいドキュメントを書くコツ(1)：読み手をイメージする
はじめに
弊社のサイトを訪問して下さる方の多くはSE（システムエンジニア）やプログラマーの方ではないかと思いますが、皆さんの中にはコードを書くのは得意だけどドキュメントは苦手という方が意外と多いのではないでしょうか。
しかし、こういった仕事をしていると要件定義書、設計書、機能仕様書、取扱説明書などドキュメントを書く機会というのは思っている以上に多いため、私達はコードだけではなくドキュメントスキルも求められています。
私自身も最初は、わかりやすいドキュメントが書けずに何度もやり直したものですが、自分なりに、わかりやすい文章とはなにかを模索したり、何度も書き続けるうちに少しずつコツのようなものが掴めてきました。
ここでは、その「わかりやすいドキュメントを書くためのコツ」を複数回に渡って紹介したいと思います。
誰かに読んでもらうために書く
ドキュメントというものは誰かに読んでもらうために書くものです。
言い方を変えると、読む人がいるから書く必要があるとも言えます。
ですから、私達が書くドキュメントは読んだ人が理解できて、そこから必要な情報を得ることができる書き方になっていなければなりません。
ここで重要なのは「読んだ人が理解できる」ということです。自分が理解できても、読む人が理解できなければ意味のないドキュメントになってしまいます。
では読む人が理解できる文章を書くにはどうしたらいいでしょうか。
誰が読むのかを、書く人がイメージする
一つは、書く人が読む人（＝ターゲット）をイメージするということです。
このドキュメンを読む人は何が知りたくて読むのか、その人は詳しい人なのか、それともよく知らない人なのか…など、できるだけ具体的にイメージするのがコツです。
例えば、詳しい人が読むのであれば、専門用語を使って説明したほうがわかりやすいのに対し、同じ説明をよく知らない人が読んだ場合、専門用語の意味がわからないとそこでつまづいてしまいます。このようなケースでは専門用語よりも誰にでもわかる表現を使ったほうがよいでしょう。
「詳しい人も読むし、よく知らない人も読むんだよなぁ」という場合は、専門用語には補足説明をつける、文章だけではなく図や表で表現するなどの工夫をすることで、読む人が自分の知識レベルに合わせて読み方を選択することができますね。
まとめ
読む人をイメージせずに書かれたドキュメントは、「誰に向けて何を書くか」が精査されていないことが多く、その結果、本来の使命を果たせないドキュメントになりがちです。
「読んだ人が理解できる」文章を書くには、まず読む人がどんな人なのか、どんなことを知りたいかというのを、書く人自身が具体的にイメージできていることがとても重要です。
書く人が書きやすいように書くのではなく、読む人が読みやすいように、というのを常に意識するように心がけましょう。
また、「何のために、何をする必要があるのか」を意識することは、ドキュメントに限らず自分がこれから行う作業のゴールを明確にし、効率良く進めていくために必要なプロセスです。
普段からこのような考え方のクセをつけておくと、ドキュメントを書く際にも自然と意識することができるようになります。
- 読み手をイメージする
- 章立てを考える
この記事を書いた人
-
トラスティアの受託開発メンバー。
好きな言葉は“死ぬこと以外、かすり傷”
最新の投稿
仕事術2017年10月4日わかりやすいドキュメントを書くコツ(2)：章立てを考える
仕事術2017年7月6日わかりやすいドキュメントを書くコツ(1)：読み手をイメージする
