テクニカルライティング３

読者に合わせた文書作成
ドキュメント
1. 文書の範囲を明記する良い文書は、その範囲を定義することから始まります。例えば
2. より良い文書は、さらにそのノンスコープ（対象読者が文書でカバーされることを期待するかもしれないカバーされていないトピック）を定義します。例えば
読者を明示する
重要なポイントは最初にまとめる
1. 比較対照
最後に

読者に合わせた文書作成

　読者のニーズに応える文章を書くには、無私の共感が必要。自分の好奇心ではなく、読者の好奇心を満たす説明を作らなければなりません。読者に文書を合わせるために、どのように自分自身から一歩踏み出すのかが重要です。そのための要点を下記に示します。

語彙とコンセプト語彙を読者に合わせましょう。単語を参照してください。

　近接性に留意します。あなたのチームの人は、おそらくあなたのチームの略語を理解しているでしょうが、他のチームの人は同じ略語を理解しているでしょうか？対象が広がれば広がるほど、より多くのことを説明しなければならなくなる。

　同様に、あなたのソフトウェアチームの経験豊富な人たちは、おそらくあなたのチームのプロジェクトの実装の詳細やデータ構造を理解しているでしょうが、それ以外のほとんどすべての人（あなたのチームの新しいメンバーを含む）は理解していません。チームの経験豊富なメンバーに向けて特別に書くのでなければ、通常、予想以上に多くのことを説明しなければならない。

知識の呪い

　専門家はしばしば「知識の呪い」に悩まされます。つまり、あるトピックについての専門的な理解が、新参者への説明を台無しにしてしまうということです。専門家としては、自分がすでに知っていることを初心者が知らないということを忘れがちです。初心者は、専門家が説明するのを止めないような微妙な相互作用や深いシステムに一応言及している説明を理解できないかもしれません。
　初心者から見れば、知識の呪いとは、まだコンパイルされていないモジュールによる「ファイルが見つかりません」というリンカーエラーなのです。

簡単な単語

　英語は世界的にテクニカル・コミュニケーションの主流言語となっている。しかし、かなりの割合の技術系読者は、英語以外の言語の方が快適である。したがって、複雑な単語よりも単純な単語を優先し、時代遅れの英単語や複雑すぎる英単語は避けるようにする。冗長な単語や珍しい単語は、一部の読者の反感を買います

文化的中立性とイディオム

　文化的に中立な文章を心がけましょう。あるソフトウェアの仕組みを理解するために、読者にNASCARやクリケット、大相撲の複雑さを理解することを求めてはいけません。たとえば、野球の比喩をアップルパイのようにアメリカ風に詰め込んだ次の文章は、パリの読者を困惑させるかもしれません

例英語圏の文章：「He really hit a home run with that idea.」

　フランス語圏の読者：「ホームランって何？（野球のルールも知らないし…）」と困惑する可能性が高い。
　文化的な比喩や表現は、読者層を考慮して使うことが大切という教訓も含まれています。

イディオムとは、

　イディオム とは、全体的な意味がそのフレーズに含まれる個々の単語の文字通りの意味とは異なるフレーズのことです。例えば、以下のフレーズはイディオムである：

a piece of cake（訳：楽勝）
Bob’s your uncle（訳：大丈夫）

　ケーキ？ボブ？アメリカの読者のほとんどは最初の慣用句を認識し、イギリスの読者のほとんどは2番目の慣用句を認識します。イギリス人読者に向けて書くのであれば、Bob’s your uncleで十分です。しかし、海外の読者に向けて書くのであれば、そのイディオムを書き換えてください。

イディオムは私たちの会話に深く浸透しているため、イディオムの文字通りの意味ではない特別な意味は私たちには見えなくなります。つまり、イディオムは知識の呪いのもう一つの形なのです。

　あなたの読者の中には、あなたの文書を読むために翻訳ソフトを使っている人がいることに注意してください。翻訳ソフトは、平易で単純な英語よりも、文化的な言及や慣用句に苦労する傾向がある。

ドキュメント

　文章は書ける。段落を書くことができる。それらの段落をすべて、首尾一貫した文書にまとめることが重要です。

文書の範囲を明記する良い文書は、その範囲を定義することから始まります。例えば

　この文書はプロジェクト・フランバスのデザインについて記述する。

より良い文書は、さらにそのノンスコープ（対象読者が文書でカバーされることを期待するかもしれないカバーされていないトピック）を定義します。例えば

　この文書では、関連技術であるProject Froobusのデザインは説明しません。

　スコープとノンスコープの記述は、読み手だけでなく、書き手（あなた）にとっても有益です。執筆中、文書の内容がスコープから逸脱した場合（あるいは、スコープでない部分に踏み込んだ場合）、文書の焦点を絞り直すか、スコープ・ステートメントを修正しなければなりません。初稿を見直すときは、スコープ・ステートメントを満たすのに役立たない部分は削除しましょう。

読者を明示する

良い文書は、読者を明確に指定しています。例えば
この文書は以下の読者を対象としています：
　ソフトウェアエンジニア
　プログラムマネージャー

読者の役割だけでなく、良い読者宣言には、前提となる知識や経験が明記されている場合もあります。例えば
このドキュメントは、あなたが行列の乗算とバックプロパゲーションの基礎を理解していることを前提としています。

場合によっては、読者宣言には前提条件となる読書やコースワークも明記する必要があります。例えば
　この文書を読む前に、”Project Froobus：この文書を読む前に、”Project Froobus: A New Hope “を読まなければならない。

重要なポイントは最初にまとめる

　エンジニアや科学者は忙しいので、あなたの設計書の76ページすべてを読むとは限りません。あなたの同僚が、あなたの文書の最初の段落しか読まないかもしれないことを想像してみてください。したがって、文書の冒頭で読者の本質的な質問に答えられるようにする。

　プロのライターは、読者が2ページ目まで読んでくれる確率を高めるために、1ページ目にかなりのエネルギーを注ぎます。しかし、どんな長い文書でも、冒頭は最も書きにくいページです。1ページ目を何度も修正する覚悟で臨むといいでしょう。

比較対照

　あなたのキャリアにおいて、どんなに創造的であっても、真に革命的なアイデアを含む文書を執筆することはほとんどないでしょう。あなたの仕事のほとんどは、既存の技術やコンセプトの上に構築される、進化的なものでしょう。そのため、あなたのアイデアを、読者がすでに理解しているコンセプトと比較対照してかく。例えば

この新しいアプリはFrambusアプリに似ていますが、グラフィックがより良くなっています。

あるいは

Froobus APIはFrambus APIと同じユースケースを扱うが、Froobus APIはもっと使いやすい。