9. 対象読者

このコースを作成した私たちは、読者であるあなたが数式を見て気分を害することはないだろうと考えています。というわけで、この章は数式から始まります:

良いドキュメント = 読者がタスクを行うために必要な知識とスキル — 読者が現在持つ知識とスキル

言い換えれば、あなたの書くドキュメントは読者が必要としていてまだ知らない情報を提供するべきだということです。この考えに基づき、この章では次の事項を説明します:

次のビデオを見れば分かるように、対象読者を見誤ると何も伝わりません:

対象読者を決める

本格的なドキュメントでは対象読者を定める作業に相当の時間と労力が費されます。こういった作業にはサーベイ・ユーザーエクスペリエンスの研究・フォーカスグループ・ドキュメントのテストなどが関係します。あなたにそんな時間はないでしょうから、ここではより簡単なアプローチを説明します。

対象読者を決めるときは、読者の肩書き (role) を決めることから始めてください。肩書きの例を次に示します:

技術に関係のない肩書きを持つ人が優れた技術や数学のスキルを持つのは素晴らしいことです。しかしそうは言っても、肩書きが対象読者を決める上で重要な一次近似であることには変わりありません。同じ肩書きを持つ人は一般的に特定のスキルや知識を共有します。例えば:

同じ肩書きを持つ人が正確に同じ知識を持っていたら、執筆はどれだけ簡単になることでしょうか。残念ながら同じ肩書きを持つ人であっても持っている知識には大きな幅があります。アマルは Python のエキスパートで、シャロンの C++ をよく知っていて、ミカは Java の専門知識を持っていて、カラは Linux が大好きで、デイビッドは iOS しか知らなくて...。

肩書きだけでは対象読者を決めることはできません。それに加えて、必要な知識に対する読者の近さ (proximity) を考えに入れる必要があります。Frombus プロジェクトのソフトウェアエンジニアは関連する Dingus プロジェクトについて多少は知っているでしょうが、関係のない Carambola プロジェクトについては何も知らないでしょう。平均的な心臓の専門家は平均的なソフトウェアエンジニアより耳について多くの知識を持ちますが、それでも聴覚訓練士に比べれば知識はずっと劣るはずです。

時間も知識との近さに影響します。例えばほとんど全てのソフトウェアエンジニアは微積分を学んだことがあるはずですが、仕事でほとんど微積分を使わないので、その知識は時が経つにつれ失われていきます。逆に、あるプロジェクトで長く経験を積んだエンジニアは同じプロジェクトの新しいエンジニアよりも現在のプロジェクトに関する知識をずっと多く持ちます。

対象読者の解析の例

次に示すのは、Zylmon という架空のプロジェクトに対する対象読者の解析の例です:

The target audience for Project Zylmon falls into the following roles:

  • software engineers
  • technical product managers

The target audience has the following proximity to the knowledge:

  • My target audience already knows the Zyljeune APIs, which are somewhat similar to the Zylmon APIs.
  • My target audience knows C++, but has not typically built C++ programs in the new Winged Victory development environment.
  • My target audience took linear algebra in university, but many members of the team need a refresher on matrix multiplication.

(Zylmon プロジェクトの対象読者は次の肩書きを持つ人物である:

  • ソフトウェアエンジニア
  • テクニカルプロダクトマネージャ

対象読者と関連する知識の関係は次の通りである:

  • 対象読者は Zyljeune API (Zylmon API にいくらか似ている API) を知っている。
  • 対象読者は C++ を知っているが、大部分は新しい Winged Victory 開発環境で C++ プログラムをビルドしたことがない。
  • 対象読者は大学で線形代数の講義を取っているが、チームメンバーの多くは行列の掛け算について復習を必要とする。)

読者が学ぶべきことを見定める

対象読者が目標を達成するために学ぶ必要があることを全てリストにして見せるようにしましょう。場合によっては対象読者が行うべきタスクもリストに加えるべきです。例を示します:

After reading the documentation, the audience will know how to do the following tasks:

  • Use the Zylmon API to list hotels by price.
  • Use the Zylmon API to list hotels by location.
  • Use the Zylmon API to list hotels by user ratings.

(このドキュメントを読み終われば、読者は次のタスクをこなす方法を理解できる:

  • Zylmon API を使ってホテルを値段順に並べる
  • Zylmon API を使ってホテルを位置順に並べる
  • Zylmon API を使ってホテルをユーザーの評価順に並べる)

タスクを特定の順番に沿って習得する必要がある場合もあります。例えば新しい開発環境を使った様々な種類のプログラムの書き方を学ぶには、その前にプログラムをビルドして実行する方法を学ぶ必要があるでしょう。

設計仕様書を書いているなら、このリストには読者が学ぶべき情報だけを入れて、習得すべき特定のタスクは省くべきです。例えば次のようにします:

After reading the design spec, the audience will learn the following:

  • Three reasons why Zylmon outperforms Zyljeune.
  • Five reasons why Zylmon consumed 5.25 engineering years to develop.

(この設計仕様書を読み終われば、読者は次のことを理解できる:

  • Zylmon が Zyljeune より優れている三つの理由
  • Zylmon が開発に 5.25 人年が費やされた五つの理由)

ドキュメントを対象読者に合わせて書く

読者の要求に応える文章を書くには自己を抑えて読者に寄り添うことが必要です。あなたの好奇心ではなく読者の好奇心を満たすための説明をしなければなりません。自己を排し、ドキュメントを読者に合わせるには何をすればよいのでしょうか？ 残念ながら簡単な答えをここに書くことはできませんが、注目すべきパラメータをいくつか示すことはできます。

語彙と概念

文章中の語彙を読者の知っている語彙に合わせてください。3. 単語 も参考にしてください。

文章で使われる知識と読者の近さを意識してください。あなたと同じチームの人ならおそらくチームの中で使われる省略語を理解できますが、他のチームの人は理解できるでしょうか？ 対象読者が広がればそれだけ、説明すべきことも増えます。

同様に、あなたと同じチームで長く働いてきた人であればチームが取り組むプロジェクトの実装の詳細とデータ構造を理解できるでしょうが、それ以外のほぼ全員 (例えばチームの新メンバー) は理解できません。あなたのチームで長く働いてきた特定の人物に対して書くのではない限り、あなたが行うべき説明は想像より多くなることでしょう。

知識の呪い

専門家はよく知識の呪い (the curse of knowledge) に悩まされます。知識の呪いとは、あるトピックの専門的な理解により初学者に対する説明が分かりにくくなる現象のことです。一度トピックを理解すると、自分が知っていることを初学者が知らないという事実は簡単に忘れられてしまいます。込み入った関係や複雑なシステムを専門家が次々に説明していっても、ほんの少し触れただけでは初学者は理解できないかもしれません。

初学者の視点から見れば、知識の呪いはモジュールがコンパイルされていないことによる "File not found" リンカエラーと言えます。

練習問題

  1. プログラミングをしたことがない医師に向けた論文の最初の段落が次の文章だったとします。知識の呪いによって分かりにくくなっている部分を指摘してください。

    C is a mid-level language, higher than assembly language but lower than Python and Java. The C language provides programmers fine-grained control over all aspects of a program. For example, using the C Standard Library, it is easy to allocate and free blocks of memory. In C, manipulating pointers directly is mundane.

    (C は中水準の言語であり、その水準はアセンブリ言語より高く Python や Java より低い。C 言語を使うと、プログラマーはプログラムの全ての部分を細かく制御できる。例えば C 標準ライブラリを使えばメモリのブロックの確保と解放が簡単に行える。C において、ポインタの直接的な操作はありふれたものである。)

  2. 上の段落が Python を知っていて C を知らない情報科学科の学部生に向けられたものであるとします。そうした場合でも知識の呪いによって分かりにくくなっているでしょうか？

  1. この段落は知識の呪いによって非常に分かりにくくなっています。対象読者がプログラミングを全くしたことがないのなら、次の用語は不適切あるいは聞きなれない単語と言えます:
    • language (言語)
    • mid-level language (中水準の言語)
    • assembly language (アセンブリ言語)
    • Python
    • Java
    • program (プログラム)
    • C Standard Library (C 標準ライブラリ)
    • allocate and free blocks of memory (メモリのブロックを確保・解放する)
    • pointers (ポインタ)

  2. 対象読者が Python を知っていて C を知らない情報科学科の学部生だったとしても、この文章は知識の呪いから逃れられていません。平均的な Python プログラマーはメモリやポインタの操作を意識しないからです。C と Python を比較して違いを説明する文章の方が最初の段落として適しているでしょう。

簡単な単語を使う

英語は技術的なコミュニケーションにおいて世界中で使われる言語となっています。しかし、技術文書の読者の大部分は英語が母語ではありません。そのため複雑な単語ではなく簡単な単語を使うようにしてください。難解な単語、使用頻度が低い単語、過剰に複雑な単語は避けてください。晦渋sesquipedalianでめったに使われない単語は読者を擯斥repelします。

文化的中立性とイディオムを意識する

文章は文化的中立性を保って書いてください。ソフトウェアの一部分の動作を理解するのに NASCAR やクリケットあるいは相撲の知識が必要なのは理想的ではありません。例えば次の文章は野球 ──アップルパイと並んでアメリカ的なもの── の比喩を使っていますが、ペルシャ人の読者を困惑させるかもしれません:

If Frambus 5.0 was a solid single, Frambus 6.0 is a stand-up double.

(Frambus 5.0 が確実なシングルヒットなら、Frambus 6.0 は楽々セーフの二塁打だ。)

イディオム (idiom) とは文字通りの意味とは全く異なる意味で使われるフレーズのことです。例えば次のフレーズはイディオムです:

ケーキ？ ボブ？ アメリカの読者なら一つ目のイディオムが分かり、イギリスの読者なら二つ目のイディオムが分かるでしょう。もしイギリス人だけに対して書いているのであれば "Bob's your uncle" を使っても構いません。しかし国際的な読者を想定しているなら、このイディオムを "this task is easy" に置き換えてください。

イディオムは私たちの会話に非常に深く染み込んでいるので、意識しないと文字通りでない特別な意味で使われていることに気が付くことができません。つまり、イディオムは知識の呪いの一種です。

読者の中には翻訳ソフトを使ってドキュメントを読む人もいる点に注意してください。翻訳ソフトは文化的な知識やイディオムの意味を知らないと読めない文章よりも、分かりやすい簡単な英語で書かれた文章を上手く扱えます。

練習問題

次の文の問題を指摘してください:

  1. As of Version 3.0, it was still kosher to call the Frambus method.

    (Version 3.0 では、まだ Frambus メソッドを呼ぶのは清浄だった。)

  2. Deciding which BlogResource constraints are combinable is a sticky wicket.

    (どの BlogResource が組み合わせられるのかを判断するのは湿ったウィケットだ。)

  3. Be that as it may, you still have to write unit tests.

    (それはともかく、あなたは依然としてユニットテストを書かなければならない。)

  1. 一部の地域では "kosher" ([食べ物が戒律に従って料理され]清浄な) が "合法な使い方" を意味します。しかしそれ以外の地域に住む多くの読者は、食事に関する宗教上の戒律とソフトウェアの間に何の関係があるのかと不思議に思うことでしょう。
  2. "sticky wicket" はイギリスのスラングであり、他の国では理解されません。この部分を "challenging problem" (困難な問題) に置き換えれば問題を修正できます。
  3. "be that as it may" はイディオムです。この転換語を "however" に置き換えれば問題を修正できます。
広告
このページの文章はテキストゆれないくんを使って校正されました。