ノンプロ研 技術ライティング講座５日目　文章を書く技術２-２　リーダブルに書く技術

リーダブルに書くにはどうしたら良いんだろう？

こちらの続きです。

リーダブルに書くための作法

１　一度に一つのことを（⇔一度にいくつもやらない）

一つの情報に関して「。」を付けて完結させる。一つずつ完結させる。

①　一つの要素に２つ以上混在させない。

文、段落などどのレイヤーでもすべてにおいてそれぞれの単位で完結させる

②　次のトピックに入る前に回収して結論づける

③　混在している場合は分割する

２　明確にする

必要な情報を書いた方が読み取ろうとしたときにわかりやすい。

①　主語、述語を確実に関係させる

日本語の場合主語をなくしても文として成立することが結構あるが、何が主語がわからなくなる文章は避ける。名詞が複数ある場合などは対応関係をはっきりさせる。

②　指示語を使いすぎない（あれ、これ、それ）

何を指しているのかわからない言葉はなるべく避ける。

「以前のコードで○○しましたが…、」以前のコードって何？となるので「３－１のコードで○○しましたが…、」というように書く。

③　二重否定、逆説ではない「○○が」を避ける

否定に使われる場合もあるし、そうでもない場合もある。

逆説なのかな？と脳みその中で考えてしまうのでなるべく避ける。

④　受け身を避ける

読み解くの負荷がかかるので受け身を使わずに書けるのであれば避ける。

⑤　メタ情報を付与する

メタ情報とは情報を説明するための情報（○○オブジェクトなど）

「ｘ」というと何？となるけど「変数ｘ」と言われるとわかる。

メタ情報を付与しないと文章がわからなくなる。

※メタ情報の持つ言葉の意味を理解していないと使えないので理解する。

３　ガイドする

接続詞を使うと次の展開を１ワードでガイドできる。脳みそが準備をできるので読む人にとってわかりやすくなる。

①　接続詞を使う（だから、するとなど）

次の文章がどういう展開になるかを準備できる。脳みそにその準備をさせることができるので読む方としてはありがたい。

②　予告する（目的地を伝える）

「これから何をするよ！」「これから大変だよ！」ということを伝える。

③　これからの概要・ようす・項目数

「今回の記事では○○の記事を３つ伝えます」というと準備ができる。

④　立ち止まらせる

別のパターンの要素を用意して立ち止まらせる。

・コードを載せる・写経する

文章→コード（写経・別のアプローチで理解してもらう）

⑤　補足する

必ずしも伝えなくてもいいけど入れた方がいいかなと言うものをメモで入れる。

・全ての読者に読んでもらいたいときは文章

・物足りなさを感じている人がいるだろうなともったときにはメモで追加する

４　見た目をやさしく

見た目も情報を持っているので、見た目にも気を使いましょう！

①　句読点

「、」「。」など

②　分割する

一度に一つのことでも分割する。文を分ける。「、」で区切る。区切ると空白が生まれてやさしく感じられる。

③　空行

隙間を作ると余裕が生まれるので、そんなに難しくなさそうだなと思わせられる。

④　ひらく

漢字をひらがなに変える。（たとえば、すべて、もっとも）

⑤　強調する

キーワードに太字を使うなど。

⑥　図・表・箇条書きの活用

文章で書いていくと詰め詰めになってしんどくなる。表や箇条書きの方が有効な場合がある。その場合は積極的に使う。すべて文章で表現しなくてよい。

５　一貫性をもたせる

①　用語・表記を統一する

②　大文字・小文字

WEB、Webなど。どちらかで統一する。

迷ったら慣習にならう。権威のある記事を参考にする。

③　記号・数字（１年、1年、一年）

統一した方が良い。全角の数字、半角の数字、漢数字。

数字を入れた方が変化が生まれるので読みやすくなる。

④　語尾

だ・であるで書いているときは途中からです・ますに変えない。

⑤　長音

サーバー・サーバなど。統一する。

⑥　パターン

一度パターンを使ったら次も同じパターンを使う

○○には××

△△には▲▲など

上位のクラスから順番に説明していくというパターンで書いているときは途中で変えない。

文単位でパターンを守るというのもあるが構造単位でパターン維持していく

⑦　正式名称を使う

⑧　慣習にならう

悩んだら慣習にならう。公式ドキュメントにならう。

６　適切な密度で

密度とは文字数あたりの情報量。

①　現時点でもっとも情報密度の高いワードを選択する

ターゲットは初心者？ある程度知識がある人？

その人にとって最も情報密度の高いワードを選択する。

②　ワードを定義する

情報密度の高いワードを選択するそれ以前にワードを定義する。ワードを獲得させる。

３　既知の情報は何度も書かない

一度書いたものはそのときに理解してもらうもの。角度を変えて書くのも良いけど同じことを何度も書く必要はない。

７　自然な構造にする

①　自然に並べる

時系列。空間の順番に並べる。

理解の順番。理解していくときに度の順番で説明した方が理解できるかを考える。

②　自然にグルーピングする

粒度とは構成単位の粗さ・大きさ

１日単位、月単位、年単位。

今どの粒度で話をしているか、別の粒度のものが入っていないかを考える。

もれなく、ダブりなく説明した方が理解がしやすい。