ライティングスタイル

ドキュメントをたくさん書くことで情報共有ができる一方、難解なドキュメントは読む側に余計な工数をかけてしまいます。丁寧なドキュメント作成を行うだけで、効率的に情報の共有ができます。 このesaでは、私が経験してきた効率的にライティングする方法、読みやすい文章を書く方法を記載します。

前提

まずは以下を理解しておくと気が楽になります。

• 読者はドキュメントを読みたいとは思わない
• 読者は全文読まない
• 読者は上から順に読まない
• 読者は最後まで読まない
• 読者にとっては、全てのページが最初のページである

Note Mark Baker著のEvery Page is Page One という本のタイトルから引用。

読者を理解する

上記を理解した上で、我々は読者の気持ちになってドキュメントを書く必要があります。

• 読者は何を知っているのか？
• 読者は何を知りたいのか？
• 読者はどれだけ知りたがっているのか？

テクニカルライティングとは？

テクニカルライティングとは、下記３点が網羅されたドキュメントの書き方のことです。

• 正確：正しい情報が掲載されている
• 効率：費やした資源が最小で理解できる
• 満足：読後に目的が達成できている

Note ユーザビリティの定義と近いので、テクニカルライティングはUIデザインの一部と捉える方もいます。

テクニック例文

それでは具体的なテクニックを紹介します。

一文一義にする

一文一義というのは「一つの文章に一つの情報だけを書く」ことです。 一つの文章の中に含む情報を一つに絞ることで、簡潔で読みやすい文章になります。

簡潔に書く

長い文章はどうしても読みづらくなります。可能な限り簡潔に、削除できる箇所は削除することが大事です。

• １センテンスはできる限り短く
• 前置き、接続詞、修飾後などは削る
• 無駄な単語は極力削る（ーのである。ーと言われている。ーと思う。）

具体的に書く（操作内容は明確に書く）

• 特にユーザに操作を依頼する場合、何をすれば具体的に明確に書く
• 曖昧な表現を避ける

結論から書く

残念ながら、ドキュメントを上から下まで一言一句漏れなく読む方はほとんどいません。特にWebサイトにおいては、文章の前半を読むだけで自分の目的とする内容でなければ離脱してしまいます。 そのため、文章の前半で「この文章は〇〇について書いてます」ということを示す必要があります。「言いたいこと」->「その理由」の順で書きましょう。

列記には箇条書きを利用する

人が一度に覚えられる項目の数には限界があります。しかしながら、箇条書きを利用することで、複数の項目が並んでいても読みやすくなります。（ライティングには見た目も重要。）

見出しで情報の区切りを明確にする

くり返しになりますが、ユーザは文章をしっかり読みません。そこで、各段落には何が書かれているのかをぱっと見で理解させる必要があります。 そこで効果的なのが見出しです。見出しにより下記の効果が生まれます。

• ユーザは次に始まる話題の予測ができる
• 読む必要のない項目をスキップし、必要な項目へ早く辿り着ける

二重否定を避ける

二重否定を利用すると、伝えたいことがうまく伝わらず混乱を招きます。 「〇〇すると▲▲します」という伝え方にします。

指示語を使わない

「こちら」「その」等の指示語はぱっと見で何を指しているのか不明になります。指示語は使わずに具体的に書きましょう。

語調は統一する

一文の中で語調が異なると読んでいて違和感が出てきます。 語調は統一しましょう。

必ず自分でも推敲する

最後に、必ず自分でも推敲してください。 推敲のポイントとしては、

「文章全体」 -> 「１段落」 -> 「１文」 ->  「単語」

の順で見ていくと推敲しやすくなります。 また、音読もオススメです。音読をすることで、文章の長さや読みにくさに気づくこともあります。

文章全体

• 全体の流れで矛盾がないか
• 順番は適切か
• 全体的に読みやすいか。

１段落

• 見出しは適切か
• 見出しと本文があっているか

１文

• 長さは適切か
• 句読点の使い方は正しいか
• 文法に間違いはないか
• 回りくどい言い方になっていないか
• 脱字はないか

単語

• 単語の間違いはないか
• 誤字はないか

なお、推敲は文章作成後すぐではなく、少し時間を置いてから読み返す方が客観的に見直すことができます。時間に余裕がる場合は一晩寝かせてから読み返すことをお勧めします。

また、第三者に見てもらうと自分では気づかなかった視点でアドバイスをもらうことができます。チームメンバーにレビューを依頼しましょう。