| [前回記事] | [トップ] | [次回記事] |
2001年4月号掲載 よしだともこのルート訪問記
番外編 ドキュメントの重要性と限界について考えること
毎月の取材記事を通じて、また、そのほかの活動を通じて、複数の場面に共通する問題点が見えてくることがあります。そこで今月は少々趣向を変えて、いま、一番気になっていることについて、私の言葉でまとめてみます。
■ドキュメント化の重要性
常日ごろから、ドキュメント化の重要性を声高らかに訴えています。なぜなら、だれかの頭の中にあることを多くの人に伝える唯一の方法がドキュメント化だと思うからです。「あの人に聞けば分かる」というのは便利ですが、「あの人に聞かないと分からない」というのは非常に不便で、限界があります。ドキュメント化の具体例は、次のようになります。
- すでに質問された内容を蓄積し、参照を可能にする
- ユーザーマニュアルの整備
■ドキュメントを整備しても人に聞く本当の理由
しかし、この大学にもすでに、学生用のドキュメントは存在していました。また、通称『HSL本』注1をはじめとする、UNIX関係の一般書も多く用意されていますが、どうもあまり使われていません。その理由の1つには、目的の情報が探せないことがありました。そこで、私は何か聞かれたときに、「ここに書いてあるよ」と、目的の情報のページを開いて渡す試みを続けてきましたが、「読んでも分からない」という返事も多いのです。
たとえば、UNIXを使っていて「私が以前作ったファイルは、どのディレクトリにあるの？」という場合、（ディレクトリを移動する）cdコマンドの使い方と、（そのディレクトリにあるファイルを一覧する）lsコマンドのそれぞれの使い方を知るだけではダメで、それを組み合わせて使う能力が必要になります。
それ以前に、cdとlsの使い方の説明文を読んで理解できる必要もあります。このとき、階層ディレクトリ構造の知識がなければ、cdコマンドの説明文もチンプンカンプンなのです。
以前、ルート訪問友の会のメーリングリスト注2に、「パソコン自体よく分からない初心者です。Linuxという夢のある未知の世界があると友人から教えてもらい、いろいろサイトをのぞいてみたのですが、チンプンカンプンでした」というメールが流れたことがありました。これに対して、鴨浩靖さん（自他ともに認める、よしだともこブレーン注3）は、次のように答えられました。
|
一般に、ある文章がチンプンカンプンである原因は、大きく分けて2つある。 (1)書き手が想定する読者層に含まれない人が読んだ (2)書き手自身が理解できていないことを書いている |
そして、1998年後半のLinuxブーム以降、残念ながら(2)に該当する著者が増えてしまったと、鴨氏は指摘されました。それも事実なのでしょうが、ここでは(1)について、より深く考えてみたいと思います。
せっかく苦労して情報（技術や操作方法）をドキュメント化しても、著者が想定する読者層に含まれない人には、理解してもらえないのです。その結果、気軽に聞ける人が周囲にいる場合、やっぱり人に聞きます。しかし、身近にそのような人がいないのがほとんどのケースでしょう。では理解するための基礎知識を身につけるために、どうすればよいのでしょうか。
■対象読者層の広いドキュメントを読むことから
基礎知識というのは、知らず知らずのうちにつくのが理想です。変な例ですが、私の父が大の相撲好きだったので、たとえば「カド番大関注4」という言葉を知らない人が世の中にいること自体が、私には不思議に思えますが、この言葉は常識とはいいきれないようです。苦労少なくして基礎知識をつける方法は、その分野の会話を分からなくても聞き続けて、ときには親切に質問に答えてくれる人に疑問をぶつけて、知識を結び付けていくことでしょう。
しかし、そんな環境にいないほとんどの人には、自分が対象読者に入ったドキュメントを探して読むことが、基礎知識をつける一番の方法だと思います。
では、想定する読者層の広いドキュメントを書きたい場合、著者はどのような工夫をすればよいのでしょうか。
私が工夫している点の1つは「専門用語には、さりげなく修飾語をつける」という方法です。前述のcdとlsの前に括弧に括ってつけた修飾語がその例です。また、この文章の前半には「CVSを使い」という表現を、あえて修飾語をつけずに登場させてみましたが、CVSという存在を知らない人を想定読者に含む場合は、それでは不親切です。
この場合、「CVSを使い」と書く代わりに「分散開発環境を可能にするシステムとして注目されている、CVS（Concurrent Versions System）を使い」と書きます。そうすれば、読者は「ふーん、CVSというのは、分散開発環境を可能にするものとして注目されていて、共同のドキュメント開発にも使えるのね」というように、新しい概念を理解しながら、その文章が読み進められるからです。
ちなみに「ルート訪問記注5」は読者対象の広いドキュメントとしての自信があります。これは、私自身に、「多くの書籍がチンプンカンプンで困った」時代があるのと、技術文書の書き方注6を学んだり、教えたりした経験があるからです。
■休載およびルート訪問本発行のお知らせ
1995年2月号の連載スタート以来、多くの方々の多大な協力のおかげで、堂々の7年目に突入していた「よしだともこのルート訪問記」ですが、しばらくの間、休載させていただくことにしました。毎号、楽しみにしてくださっている読者の皆さん、申しわけありません。では、また。
注1 通称『HSL本』
翔泳社発行の『ホップ!ステップ!Linux!』（吉田智子他 著）のこと。UNIXが基礎の基礎からマスターできる、読者対象の広い書籍である。e-book版もある。
注2 ルート訪問友の会のメーリングリスト
「ルート訪問友の会」の活動は、いろいろな場所のルートの方を訪ねて、お互いの技術や知恵を学ぶこと。
注3 よしだともこブレーン
よしだともこの活動（執筆など）を支える知的集団の総称。知らず知らずのうちにそのメンバーに加わっていることが多いようだ。
注4 カド番大関
その場所負け越す（15試合のうち敗けの方が多いと）と、大関の地位を略奪される「ピンチの大関」のこと。「大関は2場所連続負け越すと関脇に降下する」という決まりがある。大関とは、横綱の一歩手前の肩書。
注5 ルート訪問記の過去記事
http://www.tomo.gr.jp/root/から利用可。1999年の夏の時点で、1995年2月号から1999年の8月号までのすべての記事を読み直して、加筆やバージョンアップを加えた。
注6 技術文書の書き方
木下是雄著『理科系の作文技術』中公新書が、この分野の名著。
| [前回記事] | [トップ] | [次回記事] |