なんとなくで終わらせない！今こそ学ぶドキュメントライティング

はじめに

ドキュメントライティングとは、情報を明確かつ効果的に伝えるための重要なスキルです。

この記事では、私が入門 考える技術・書く技術を読んで学習したドキュメントライティングの方法を紹介します。
これを機会に感覚での資料作成を一緒に脱却していきましょう。

ドキュメントライティングの流れ

ドキュメントライティングには大きく分けて4つのステップがあります。
順番に行うことで分かりやすい文書を書くことができます。

今回の記事では、分かりやすい文章を作成するための方法について説明しています。
開発ドキュメントやヘルプページといったエンジニア関係のドキュメント作成については、エンジニアのためのドキュメントライティングを参照下さい。
ユーザージャーニーマップの作り方や、開発者の視点に合わせた構成方法まで詳しく載っています。

1. 読み手の関心・疑問を明らかにする

ドキュメントを書き始める前に、まずは「OPQ分析」を利用して読み手が何を求めているのかを考えます。

「OPQ分析」とは、ビジネスシーンでもっとも必要とされる問題解決を重要視した読み手分析手法です。

• O: Objective(望ましい状況、目標)
• P: Problem(理想と現状のギャップ)
• Q: Question(読み手の疑問)
• A: Answer(読み手へのアンサー、文書の主メッセージ)

分析を進める上で大切なことはそれぞれを考える際に「一貫したレール」を揃えることです。そして、これが文書のテーマとなります。

例

テーマ: 開発スピード
O: 開発スピードを速くする
P: 開発スピードが遅い
Q: 開発スピードを上げるためにはどうすれば良いか
A: 開発スピードを上げるために、DesignDocsの導入を提案します。

OPQ分析のコツ

• OPQは全て読み手側の視点で書く
• レールを外さず一貫性を持たせる
• A（回答）は直接Q（疑問）に答える

より良いOPQ分析を行うためには事前の情報収集が欠かせません。
読み手の疑問に対してずれた回答を述べていると、「結局どうなの？」と言われてしまいます。A,Qがそもそもおかしいこともあるため、その場合は情報収集を行い再分析しましょう。

2. 考えを組み立てる

読み手の分析が終わると、次は自分の考えを形にしていきます。

メッセージに紐付く理由は最大5つにする

人は物事を考えるときに対象のグルーブ分けを脳内で行っていて、また、人が短期記憶で覚えられる考えの数は7±2だそうです。
実際の文章でも、理由が10個もあると読みづらいですね。

理由が複数ある場合は、それらを再度グルーブ分けしましょう。
メッセージに紐づく理由、その理由に紐づくメッセージといった形で、グルーブごとのピラミッド構造になるため、分かりやすい文書構造になります。

メッセージのグルーブ化と要約を繰り返す

考えを組み立てる手法として、理由となるメッセージの要約と、主メッセージの理由のグループ化があります。

これらを相互に行うことで、バラバラのメッセージのグループ分けが行えます。

要約してグループ化を行うときにありがちなのが、一般論を挙げてしまうことです。
要約は、グループ化の根拠を示す意味のあるものにしましょう。

要約作成時に気をつけること

• 名詞表現、体言止めは使わない
• 曖昧な表現は避ける
  • 検討する、見直す、問題があるといった言葉はつい使用してしまいがちです。しかし、これらの言葉は具体性がありません
  • 使用は避け、意味のある言葉で説明するようにしましょう
• 要約は一つの文章で書く
  • 文が2つある理由は、絞りきれていないか、うまく要約されていないためです
• 前後の文章の関係性を説明しない接続詞を使わない
  • 例: ~し、~, ~であり、~, ~して、~
  • これらは英語でAND、文章を繋ぐ意味しか持っていません
  • 文章の言い換えを行いましょう

どうしても複数文で表したほうが分かりやすいこともあります。
その場合は必ず、因果関係が明確な接続詞を使用するようにしましょう。
にも関わらず、したことにより、のためにと言ったものです。

「だから、何？」を繰り返す

せっかく要約を考えたとしても、伝えたい事が明確でなければ「結局何を言いたいのか？」と言われてしまいます。
あいまいな表現を使用していると起こりがちです。

そんなときは、要約に対して「だから、何？」を考えましょう。
繰り返すことで事の本質に近づきます。

文に起こそうとすると、つい遠回しな文章を作りがちです。
しかし、このフェーズでは自分の考えを組み立てるのが目的であるため、遠回しな表現は避け、言い切り表現を使いましょう。

グループ化するときのコツ

• 人が一度に覚えられる数には限界があるため、一つの要約に紐付くメッセージは最大5つにする
• 一つのメッセージで伝えることは一つに絞る。複数ある場合はピラミッドを分割する
• 要約とグループ化を繰り返すこと
• 前後の文章の関係性を説明しない接続詞を使わず、あいまい表現を避ける
• メッセージの本質を伝えられるように「だから、何？」を繰り返す

3. まとまりごとに組み立てる

フェーズ2では、グループ化の方法を学びました。
フェーズ3では、それらの手法を使いながら、実際の文章を組み立てるようにピラミッド構造を作っていきます。

文章を書く上で重要なロジックである「帰納法」と「演繹法」の2つを利用して組み立てて行きましょう。

帰納法でロジックを考える

帰納法は、複数の理由を前提として結論を導く手法です。
今回に当てはめると、要約が結論となり、それに紐づく理由が前提です。
そのため、必ず理由は複数必要であり、結論は推論になります。

帰納法の例

結論: プログラミング言語でゲーム開発は出来る
前提1: Cでゲーム開発は出来る
前提2: Golangでゲーム開発は出来る
前提3: Javaでゲーム開発は出来る

全てのプログラミング言語でゲーム開発が出来るとは言えませんが一般論としては筋が通っています。

帰納法をピラミッドに適用するコツ

• 前提は同じ種類の考えにする
  • 帰納法では前提の共通点によって結論を導く
    • 前提の主部が同じ → 述部を推測
    • 前提の述部が同じ → 主部を推測
    • 前提の示す意味が同じ → 意味を結論とする
• 結論と前提を繋げる接続助詞を揃える
  • 結論と前提の間には「なぜなら」「例えば」「そう判断する理由は」というふうな接続助詞が入る
  • 同じ接続助詞が入るか、それらの意味が通るか、違和感はないかを確認する
• 結論を最初に述べる

演繹法でロジックを考える

演繹法は、一般的、もしくは絶対的に正しいとされる前提から、結論を導く手法です。

帰納法の結論はあくまでも推測に過ぎず、前提によってそれを裏付ける形でした。
しかし、演繹法では前提が正しいとすれば必然的に結論も正しくなります。

演繹法を使用する際は前提による結論を間違えないように注意してください。
例えば、日本株価が最高値を更新したからと言って、特定の日本企業が好業績だとは限りません。

演繹法をピラミッドに適用するコツ

• 導かれる結論は絶対的に、もしくは妥当と言えるのか確認する
  • 演繹法では前提からさも正しいかのような結論を出してしまいがち
  • 本当にそう言い切れるのかを改めて考える
• 前提は本当に正しいのかを確認する
  • 思い込みや認識間違いがあると、そもそもの前提が崩れてしまう

4. 実際に文章を書く

ここまで来るともう後は書くだけです。
フェーズ3で作成したピラミッド構造を保ったまま、文章を作成していきます。

ピラミッドから文章を作成するコツ

• メッセージごとに段落を作る
• 各グループの主メッセージは文の固まりの始めに置く
• 前後の文章の関係性を説明しない接続詞はなるべく使用せず、因果関係が明確な接続詞を使用する
• あいまいな表現は避け、主語を明確に示す
• 文章の導入部はOPQ分析を使用し、読み手の関心を惹きつける

まとめ

効果的なドキュメントライティングは、読み手の理解を深め、情報の価値を最大化します。
この記事が、より良いドキュメントを作成するための一助となれば幸いです。

この記事は、初学者がドキュメントライティングの学習を兼ねて作成したものです。
より詳細な情報や実践例については、実際に専門書をご確認下さい。

最後に、今回の学習にあたりお世話になった本を参考に記しておきます。
分かりやすく丁寧に説明されており、初めて学ぶ方にオススメです。

参考

• エンジニアのためのドキュメントライティング
• 入門 考える技術・書く技術