文章とか資料とか図表を書くときの注意
まとまった文章とか資料とか図表を書くとき向け。当たり前だけど気をつけるべきところなど。思いついたところから。ざっくばらんにですが。。。
その文章・資料の意味を考える
- いま書いている文章・資料は何のために書くのか
- 誰のために書くのか
- 文章の頭に「文章の目的」と「対象読者」を書いておくとよい
資料を管理できるようにする
- ページ数を降る
- 書いているひとの名前を書く
- 資料の作成日時・更新日時を頭に書いておく
文章のルールを決める
- こういうときはこう表現する、と決める
- 自己流でいいけど、分かる方法で決める。(文章内部に書く、など)
未定義かつ明らかでない表現は使わない
- 「誰が見ても明らかに意味が分かる」ときを除いて、資料上で意味を定義する。
- 赤矢印は○○という意味、太文字は○○という意味、等
何となく書かない
- そこにそれが書いてある意味を考える。
- 「そこにそれが書いてある意味は特にない」ということもある。しかし明確に区別されるべき。
- そこに書いてあるものは伝わるか？そこに書く必要があるか？そこに書くべきものは足りなくないか？
- 逆に、伝われば簡単な書き方、省略した書き方をする。常に文章は短い方がいい。
不要なクオリティを求めない
- 書いている文章がどのクオリティを目指すべきなのか考える
- 伝わればいい場合もあれば、外部に出しても恥ずかしくないにする場合、読み手に非礼がないよう丁寧にしなければいけない場合もある
- 「伝わればいい」場合は、本当に伝わりさえれば、汚くてもいい、乱暴でもいい。誤字脱字にもこだわる必要もない。日本語文章になってなくてもいい(箇条書きとか)。そこにかける時間は無駄。
- 「文章としてのクオリティ」を求める場合は、絶対に書き手以外の人がチェックする。自分では絶対誤りを見逃す。
「広く・浅く・抽象的」な説明から入り、「狭く・深く・具体的」な説明に入るように書く
- 大まかな概要説明から入って、だんだん細かく各部を説明するようにする
「一般化された表現」と「例示」を両方書く
- 一般化だけではうまく伝わらないことが多いし、例示だけだと「何のために例示したのか」が分からない。
- (例) 「max(a,b) はaとbのうち大きい方を示す。(←一般) 例えばmax(5,7) は7を示す (←例示)」
同じ表現は同じ意味、違う表現は違う意味にする
- 同じ表現なのに意味が違ったりすると混乱する
- 全て統一されていると読みやすい
- (a,b,c)と(d,e,f)は同じ意味にする、{a・b・c}と(d,e,f) は違う意味にする
- (図を書くとき) 同じ図形かつ同じ色は同じ意味、違う図形や違う色の場合は違う意味にする、などなど
「動詞(句)」と「名詞(句)」の区別をする
- システム関係では、名刺と動詞の区別を大切にするとわかりやすくなることが多々ある
- 「関数の説明は動詞にする」、「変数の説明は名詞にする」などなど (ただしこのルールが絶対ではない)