これまでのおさらい
作成フェーズ
フェーズ2（作成フェーズ）では、文章をすぐにでも書き始めたくなるところですが、いきなり文章から書き始めるのは避けましょう。もちろん、人によってはいきなり書いても、読み手のゴールを達成する文章を書けますが、ドキュメントライティングに不慣れな人の多くは、そこまで上手に書けません。結果的に、最も重要な「読み手の課題」を解決できないドキュメントが生まれてしまいます。
フェーズ2では、大きく以下の3ステップで進めるとよいでしょう。
- 構造化されたアウトラインの作成
- アウトラインを構成するパーツである段落の作成
- 段落を構成する一文の作成
構造化されたアウトラインの作成
フェーズ1（準備フェーズ）で定義した、読み手のゴールを満たすために、まずはアウトラインを先に作りましょう。読み手のゴールを最上段の目的として、ゴールの達成に資する情報（根拠・説明・例など）を構造化して追加していきます。イメージは次のような構成です。
読み手のゴールを意識しながら、アウトラインを先に作ることで以下のメリットがあります。
- 「このドキュメントは誰の何を解決するのか？」というゴールからブレない
- 書いている途中で迷子になりにくい
- 全体像と詳細のバランスを取りやすい
アウトラインの構造には、典型的なパターンがいくつかあります。
構造化パターン
読み手のゴールの達成につながるための情報は、単に羅列するのではなく、一定の規則を持たせて構造化すると読みやすい文章になります。典型的な構造化パターンは次の通りです。
1. 全体から部分へと展開する
はじめに概要・大枠を示し、その後に詳細を掘り下げる方法です。たとえば、システム全体像→各コンポーネント→その詳細、といったように徐々に具体化します。
2. 既知の事柄から未知の事柄へと展開する
読者がすでに理解している概念からスタートして、新しい情報や複雑な情報に移行します。「○○はご存知の通り△△です。一方で△△を拡張する形で、本ドキュメントでは□□を扱います」のように記述すると、情報の現在地が伝わりやすくなります。
3. 相手が知りたい事柄から説明する
技術仕様のように、単に必要な情報だけを読み手が探しているケースは非常に多く存在します。たとえば、何らかのソフトウェアのREADMEであれば、インストール手順や基本的な使い方を先に出してあげるのがこのパターンに当たります。細かなオプション設定やニッチなユースケースを満たす拡張APIなどは、後半や別ドキュメントでおさえるようにします。
4. 作業や手順を流れに沿って説明する
作業手順書や操作マニュアルなどでは、実際に行う順番に沿って記述するのがわかりやすいでしょう。「1. ○○をダウンロードする → 2. △△をインストールする → 3. □□を起動する」といった流れです。
アウトラインを構成するパーツである段落の作成
構造化されたアウトラインを作ったら、アウトラインの項目ごとに肉付けしていきます。その際、「段落ごとに、言いたいことを1つに絞る」という原則を意識します。1つの段落に複数の主張や論点を詰め込みすぎると、読み手は混乱しやすくなります。混乱を避けるために、以下の2種類のセンテンス（文）を意識しましょう。
-
トピックセンテンス（主張／要旨）
- その段落で言いたいことを一言で表します。
- 読み手が「この段落では何を言いたいのか」を素早く把握できます。読み手がこの段階で理解・腹落ちしたならば、以降は読み飛ばしてもよいように書きます。
-
サポートセンテンス（理由／根拠／例など）
- トピックセンテンスを補足する情報を挙げます。
- 読み手が、トピックセンテンスだけでは腹落ちできない・理解できない場合に活用する情報です。
- 根拠や具体例を示すと、理解を後押しできます。
段落を構成する一文の作成
一文の書き方にもコツがいくつかあります。本記事では特に意識して欲しいポイントを2つ紹介します。
節を先にして、句を後にする
『【新版】日本語の作文技術』（朝日文庫）で説明されるように「節を先に、句を後に」書くと、読みやすさが劇的に向上します。具体的な例を挙げてみましょう。たとえば「クラウド上にあるコンテナ」に対して補足を加える一文の場合、次のような語順が考えられます。
悪い例
クラウド上のユーザーが頻繁にアクセスするコンテナ
良い例
ユーザーが頻繁にアクセスするクラウド上のコンテナ
前者は「クラウド上のユーザー」と取られてしまう可能性が多少あります。一方で後者は、誤解なく読めます。順序のちょっとした違いですが、これだけで読み手の理解のしやすさに差が生じます。「クラウド上の、ユーザーが頻繁にアクセスするコンテナ」と句点を含めることによって、意図が伝わりやすくなりますが、この例では良い例で記載している一文の方がシンプルでしょう。
「代名詞」を避ける
文章を書くときに、「これ」「それ」という代名詞を多用すると、読み手と書き手で指している対象がずれることがあります。特に、以下のような場合はあいまいさを招きやすいです。
- 一つ前の文で複数の要素を挙げている
- 長い段落の最後に「それは〜」と書く
指し示している対象を繰り返しても問題ありませんし、単に「それ」と書くよりは「そのシステム」「本機能」など具体的に書くほうが安全です。
最後に読み直す
文章を書き上げたら、最後の仕上げとしてレビューします。時間に余裕があれば、次の取り組みを試してみましょう。
音読によるセルフレビュー
声に出して読むことで、目視だけでは見つけられなかった「おかしな接続」「文章の冗長さ」「誤字や脱字」などに気づきやすくなります。
3Cの観点でレビュー
優れた文章には 3C の要素が含まれている。3Cは Clear、Concise、Consistentの頭文字からなっており、それぞれ次を意味します。
- Clear（明確さ）：あいまいな表現はないか？
- Concise（簡潔さ）：短くてわかりやすいか？
- Consistent（完全性）：構造やコンセプト、語彙が一貫しているか？
この3つの観点でドキュメントを読み直すことで、さらに読み手に有用なドキュメントを作成できます。
第三者のレビュー
可能であればユーザー、同僚や別のチームメンバーに読んでもらいましょう。前回の記事で紹介したように、ドキュメントには常に知識の呪いが付きまといます。書き手には気付けない観点を知るには、自分以外の第三者に読んでもらうのが効果的です。
