私はテクニカルライターとして働いています。開発ドキュメントを書くときは、基本的にアウトラインを書いています。以前は、わかりやすい文章がなかなか書けませんでした。書けたとしても、とても時間がかかっていました。
「何とかしたい！」と思い、試行錯誤しました。その結果、自分なりのやり方を体系化でき、一定以上の品質の文章を、早く書けるようになりました。この記事を読むことで、わかりやすい開発ドキュメントを書くきっかけになればと思います。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
アウトラインとは何か
アウトラインとは、箇条書きで文章の骨組みを表現したものをいいます。最終的には、この骨組みに肉付けをしていくことによって、文章になります。アウトラインは、文章の全体像を設計するのに役立ちます。基本的には、文章を書くときはまずアウトラインを書くことになります。
アウトラインを書く必要性
アウトラインは、次の二つのために書きます。
- 読者に伝わる文章にするため
- 文章作成にかける時間を短くするため
それぞれについて、簡単に説明します。
1. 読者に伝わる文章にするため
アウトラインでは、文章の順序を仮決めして、読者の視点でわかりやすいかどうかを確認していきます。このため、話を入れ替えたり、補足したり、といった修正が簡単にできます。
アウトラインを書かずに、いきなり文章を書き始めてしまうと、次のような問題が生まれやすいです。
- あるところは詳しいけど、あるところは説明が足りていない
- 文章の順序がわかりづらい
文章を書いた後だと、文章が長く、俯瞰して確認しづらくなります。こうならないためにも、アウトラインの時点でわかりやすいかどうかを確認することが大切になってきます。
2. 文章作成にかける時間を短くするため
いきなり文章を書いてしまうと、修正が難しくなります。文章は文脈を含めて書くので、単純に構成を並び替えると、文脈がおかしくなってしまうからです。早く書こうと思って文章から書きはじめたつもりが、結果的に、文章を書くのに時間がかかってしまいます。
よりよい文章を早く書くためにも、アウトラインを書くことが重要になってきます。
アウトラインの書き方
アウトラインは、次の三つを意識して書いていきます。
- 見出しで全体像を設計する
- 見出しごとの内容を書く
- 読者にとってわかりやすくする
ひとつずつ説明していきます。
よいアウトラインを書くためには、企画として、あらかじめ「読者」と「伝えたいこと」を決めておく必要があります。企画について詳しくは、「開発ドキュメントを書く前に決めるべき3つのこと【企画編】」をご覧ください。
1. 見出しで全体像を設計する
アウトラインは、まず箇条書きで見出しを書いていきます。必要に応じて大見出し、中見出し、小見出しのようにレベルを使い分けます。このとき、インデント（字下げ）でレベルを表現します。
この見出しは、実際の目次になるイメージで設計していきます。
2. 見出しごとの内容を書く
次に見出しごとに内容を書いていきます。アウトラインはあくまで骨組みなので、肉付けはしないようにします。アウトラインの段階で詳細まで書いてしまうと、修正がしづらくなってしまいます。また、文章を書くときに、表現の自由が利かなくなったりします。
3. 読者にとってわかりやすくする
はじめに押さえておきたい考え方として、あなたが書きたいことと、読者にとってわかりやすいことは違います。まずはあなたが書きたいように書いてもいいですが、書き終えたら、読者にとってわかりやすいよう、順序を変えたり補足したりしてみます。
アウトラインが完成する条件
アウトラインは、次の二つを満たすまで修正を繰り返していきます。
- 伝えたいことを伝えられているか
- 読者にとってわかりやすいか
ポイントとしては、一度アウトラインを書き終えたら、一晩寝かせてみます。こうすることで、フラットな目線で推敲できるようになります。
ここまでできれば、文章を書く準備が整いました。実際に文章を段階になると、アウトラインにないことを書くこともありますが、これはこれで問題ありません。少なくとも、アウトラインを書くことで、わかりやすい文章を早く書くための土台ができます。
アウトラインを書くためのツール
アウトラインは、箇条書きで、かつインデントを用いながら書いていきます。つまり、次の条件を満たせば、どんなツールでも問題ありません。
- 改行時にリストになること
- インデントが保たれること
- 編集がしやすいこと
私はmacOS標準のメモアプリを使っています。ツールについては、あなたの使いやすいものを探してみてください。
例：この記事のアウトライン
参考までに、この記事を書く前に書いたアウトラインを以下に紹介します。開発ドキュメントとはちょっと違いますが、参考になればうれしいです。
* リード
* テクニカルライターとして働いている
* 開発ドキュメントを書くときはアウトラインを書いている
* 以前はわかりやすい文章が書けなかった
* またとても時間がかかっていた
* 今では自分なりにやり方を体系化した
* ある程度の質のある文章を早く書けるようになった
* この記事を読めば、わかりやすい開発ドキュメントを早く書けるようになる
* アウトラインとは何か
* 文章の骨組みを箇条書きにしたもの
* 最終的にはこの骨組みに肉付けしてくことによって文章となる
* 文章の全体像を設計するのに役立つ
* 基本的には、文章を書くときはまずアウトラインを書く
* アウトラインを書く必要性
* 次の二つ
* 伝わる文章にするため
* 話の順序を仮決めして、読者の視点でわかりやすいかを確認する
* 入れ替えたり補足したり、といった修正が簡単にできる
* いきなり書き始めると：
* あるところは詳しいけど、あるところは説明が足りない
* 順序がわかりづらい
* といった問題が生まれやすい
* 書いた後だと文章が長く、俯瞰して確認しづらい
* 作成にかける時間を短くするため
* いきなり文章を書くと、修正が難しい
* 文章は文脈を含めて書く
* 並び替えると文脈がおかしくなったりする
* 結果的に時間がかかる
* よい文章を早く書くためにもアウトラインは重要
* アウトラインの書き方
* 前提→読者、伝えたいことを決めておく
* アウトラインは次の三つを意識して書く
1. 見出しで全体像を設計する
* 箇条書きで書く
* 必要に応じて大見出し、中見出し、小見出しを使う
* インデント（字下げ）で表現する
* 実際の目次になるイメージ
2. 見出しごとの内容を書く
* 内容を書いていく
* アウトラインはあくまで骨組み
* 肉付けしない
* 詳細まで書くと修正しづらい
* 文章を書くとき、表現に自由が利かない
3. 読者にとってわかりやすくする
* あなたが書きたいことと、読者にとってわかりやすいことは違う
* まずは書きたいように書いていい
* 読者にとってわかりやすいよう、順序を変えたり補足したりする
* アウトラインの作成が完了する条件
* 次の二点を満たすまで修正する
* 伝えたいことを伝えられているか
* 読者にとってわかりやすいか
* ポイント→寝かせる
* フラットな目線で推敲できる
* これができれば、文章を書く準備が整った
* 実際に文章を書く段階になると、アウトラインにないことを書くこともある
* 問題ない
* 現時点で考えられるよりよいアウトラインを目指す
* アウトラインを書くことで、早くわかりやすい文章が書ける
* アウトラインを書くためのツール
* アウトライン→箇条書き、かつインデントで書いていく
* 以下の条件を満たせば何でもよい
* 改行時にリストになる
* インデントが保たれる
* 編集がしやすい
* 私はmacOS標準のメモアプリを使っている
* 例
* この記事で書いたアウトライン
* 開発ドキュメントではないが、参考になると思う
* おわりに
* アウトラインを書くと伝わる文章を早く書ける
* 箇条書きで、見出しと内容を書く
* 読者の視点でわかりやすいように書く
おわりに
アウトラインを書くと、伝わる文章を早く書けるようになります。このアウトラインは、箇条書きで、見出しと内容を書いていきます。アウトラインを書くときは、読者の視点でわかりやすいように書くことが大切です。
