はじめに
ぼくは、新卒2年目の自称エンジニアです。でも最近なんだかモチベが低下中です。
論文/仕様書/プレゼンなどの技術文書の内容を他者に見せた時、「ここはどういう意味？」、「ここは分かりにくいから書き直して」。そう返されて修正する日々です。最終的に他者に修正してもらうこともあって、がっかり。
目的
誰でもすぐに理解できる技術文書を書きたい！！
そのために必要なことをまとめて、成長の糧にしたい。
想定する読者
誰でも
ぼくの技術文書のよくないところ
- 書いているうちに目的とずれてくる。
思い付きで書き始めてしまうため、自分の言いたい(技術的な)ことに焦点が合ってしまって本来の目的を忘れる。 - 読者の理解に頼ってしまい、説明不足になる。
『AはBだからCである。』という文章のとき、Aが本当にそうであるか分からない。Bという理由の根拠が甘い。Cであるかどうかはっきりしない。 - ストーリーが一貫していない。
なぜそう言えるか？理由をあちこちに書いている。 - あいまい。
自身のなさの表れ。 - 文章が長くなり、複雑になる。
分かりやすくしようするあまり書きすぎてわかりにくくなる。 - 事実と意見が混ざっている。
『～は...である。』←それは言い過ぎ。ということがある。 - 用語の説明が甘い。
ぼくのマインドのよくないところ
- 読者のことを意識していない。自分の理解レベルと同じだと思っている。
- 全てを書けばよいと思っている。(書けてないが)
- 修正前提で提出している。
具体的な修正方法
- はじめに目次を書いて全体像をつかむ。
- 仮想の読者を設定する。デフォルトは小5
- あいまいな表現を検索して変換する。
『と見てもよ い』『であろう』
『と思われる』『と考えられる』
『ほぼ』 『約』『ほど』『ぐらい』
『たぶん』『ような』『らしい』
『こと』『もの』 - 根拠/理由を書く。
- 1文は2行までに短くする。
- 以上のことをチェックリストにチェックする。