-*- POD -*-
関西学院大学 理工学部 情報科学科
大崎 博之 (ohsaki[atmark]lsnl.jp)
Tips for technical writing
Hiroyuki Ohsaki (ohsaki[atmark]lsnl.jp)
Department of Informatics, School of Science and Technology, Kwansei Gakuin University
$Id: index.pod,v 1.2 2006/06/29 16:07:43 oosaki Exp ohsaki $
この文章では、具体的な例を挙げて、どのようにすれば正しい技術文書を書く ことができるかを説明します。例として、私がこれまでに指導した学部 4 年 生が作成した文章を用います。実例を挙げながら、技術文書としてどいういう 間違いがあるのか、どうすればより良い文章になるのかを説明します。
みなさんは、小学校から高校まで、国語の授業で一通り日本語については習っ ているはずですが、普段使うような日本語と、論文などで用いられる技術文章 は少し違っている点があります。技術文章では、「厳密さ、簡潔さ、読み易さ」 がとても重要です。しかし、みなさんが普段話す話し言葉や、メールや日記に 書くような日常的な文章では、それほど「厳密さ、簡潔さ、読み易さ」を意識 していないと思います。
本当なら、大学の講義で、技術文書の作成方法を学ぶべきなのですが、日本の ほとんどの大学ではそういったカリキュラムを設けていないようです。ですの で、技術文書の作成方法は基本的に独学で学ぶ必要があります。
どんなに素晴しい研究成果を出しても、それを表現することができなければ、 せっかくの研究成果も台無しです。また、技術文書を書けるようになることは、 正しい日本語を書けることと同じですので、技術文書作成の能力を磨いておけ ば、これからきっと様々な場面で役に立ちます。この文書が、みなさんの技術 文書作成力を向上される一助になれば幸いです。
技術文章では、特に以下の 3 点が重要です。
厳密であること (論理的に正しく、一意に解釈できること)
簡潔であること (複数の表現があれば、最も簡潔なものを使うこと)
読み易いこと (思考の流れを中断しないこと)
これらをもう少し具体的に言えば、以下のようになります。
以降の説明では、これらの 6 つを、技術文章作成のためののルール (R1 〜 R6) と呼びます。
ここで、私がこれまでに指導した学部 4 年生が作成した文章を紹介します。 日頃から、技術文章を書いたり、技術文章を校閲/添削するトレーニングをしてない 人が読めば、「まあなんとなく言ってることは分かるかなあ」という感想を持 たれるかもしれません。
リング型 P2P-VPN のデータの転送機能について述べる。リング型 P2P-VPN に
帰属するノードをゲートウェイと呼び、ゲートウェイは配下に通信を行うユー
ザ端末を持つ。各ゲートウェイは連続する片方向の IPsec トンネルで接続さ
れ、全体としてリング型のトポロジを構成している。通信を行いたい端末は、
まず自身が所属するゲートウェイに対してデータを送信する。配下からデータ
を受信したゲートウェイは、IPsec トンネルを通して前方のゲートウェイにデー
タを送出する。しかし、技術文章という点で考えると、数多くの改善すべき箇所があります。 以下では、この文章を題材として、「どこが技術文書として問題なのか」、 「どうやって技術文書の問題点をチェックすればいいか」、「どうやって技術 文書を校正すればよいか」を説明します。
それでは、「どこが技術文書として問題なのか」の説明から始めます。例文の 個々の文に対して、技術文章作成の 5 つのルールを満たしているかどうかを チェックします。
リング型 P2P-VPN のデータの転送機能について述べる。まず、突然すぎて何のために説明しようとしているのかが分かりません (R4)。 また、「……の……の」と助詞が連続していて読みづらい文章です
リング型 P2P-VPN に帰属するノードをゲートウェイと呼び、
ゲートウェイは配下に通信を行うユーザ端末を持つ。「帰属する」の主語があいまいです (R1)。また、「ノード = ゲートウェイ」 という意味になっていますが、これは一般的な用語の用法と異なっています (R3)。「ゲートウェイが端末を持つ」の意味が分かりません (R3)。万能動詞 「持つ」の使用は避けるべきです (R5)。「配下」の意味や、どの単語を修飾 しているのかが分かりません (R3, R4)。「通信を行う」の主語が分かりませ ん (R1)。「通信を行う」は冗長なので、「通信する」とすべきです (R6)。
各ゲートウェイは連続する片方向の IPsec トンネルで接続され、
全体としてリング型のトポロジを構成している。「連続する」がどの単語を修飾しているか分かりません (R3)。「片方向」と 「IPsec トンネル」の関係が分かりません (R3)。一般に、IPsec トンネルは 双方向です。「接続する」の主語が分かりません (R1)。「全体として」が何 を意味しているのか分かりません (R3)。
通信を行いたい端末は、
まず自身が所属するゲートウェイに対してデータを送信する。「通信」が何のことか分かりません (R3, R4)。「所属する」が何のことか分 かりません (R3, R4)。「データ」が何のことか分かりません (R3, R4)。また、 「……に対して……を送信する」ではなく、「……を……に対して送信する」 のほうが (意味を考えれば) 自然な語順でしょう。
配下からデータを受信したゲートウェイは、
IPsec トンネルを通して前方のゲートウェイにデータを送出する。「データを受信」が何のことか分かりません (R3, R4)。「 IPsec トンネルを 通して」が何のことか分かりません (R3, R4)。「前方」が何のことか分かり ません (R3, R4)。「データを送出」が何のことか分かりません (R3, R4)。
ほとんどの人は、技術文書 6 つのルール R1 〜 R6 のどれがどのように満た されていないかを指摘されれば、そのことについては納得します。しかし、 「自分ではそのことに気付かない」という声をよく聞きます。
そこで、技術文書 6 つのルール R1 〜 R6 を、どのようにチェックすれば良 いかを具体的に説明します。基本的なポイントは、「なんとなくフィーリング で文章とらえるのではなく、文章を単語単位にまで分解して、文章の論理的な 構造を細かく考える」ということです。
ここでは以下の文を取り上げます。
リング型 P2P-VPN に帰属するノードをゲートウェイと呼び、
ゲートウェイは配下に通信を行うユーザ端末を持つ。以下、それぞれのルールをどのようにチェックすればよいかを説明します。
まず、文章の文法的な構造を考えます。修飾節等は除いて、文章の骨格がどう なっているかを考えます。
ノード を ゲートウェイ と 呼び 、ゲートウェイ は 端末 を 持つ。
主語 述語 主語 目的語 述語これは、句点で二つの文が接続されています。つまり、
ノード を ゲートウェイ と 呼ぶ
目的語 述語 と
ゲートウェイ は 端末 を 持つ。
主語 目的語 述語という二つの文で構成されています。そこで、それぞれの文に対して、主語、 述語、目的語が明確かをチェックします。最初の文、
ノード を ゲートウェイ と 呼ぶ
目的語 述語 には主語がありません。主語が「我々」や「一般の人々」で自明の場合は省略 できますが、この場合は自明ではありません。二つめの文、
ゲートウェイ は 端末 を 持つ。
主語 目的語 述語は、主語、述語、目的語が明確なので問題ありません。
リング型 P2P-VPN に帰属するノードをゲートウェイと呼び、
ゲートウェイは配下に通信を行うユーザ端末を持つ。この文章では指示代名詞 (それ/これ/あれ/それら/これら/その/この/あの等) を用いていないので問題ありません。
例文は二つの文が接続されたものですので、最初の文を見てみます。
(リング型 P2P-VPN に帰属する) ノードをゲートウェイと呼ぶ。
目的語 述語「リング型 P2P-VPN に帰属する」という修飾節は、「ノード」にかかってい ます。修飾節は、基本的に最も近い単語にかかります。この場合、修飾関係に は問題がありません (論理的に正しく、一意に定まっています)。修飾節に着 目すると、
(リング型 P2P-VPN に帰属する) ノード
述語 主語となっており、主語、述語の関係は問題がありません。ただし、「帰属する」 という言葉の意味がよく分かりません。もっと平易な表現を用いたほうが良い でしょう。
次に、主語、述語、目的語の論理的な関係を見てみます。
(リング型 P2P-VPN に帰属する) ノードをゲートウェイと呼ぶ。
目的語 述語この文は、「ノード = ゲートウェイ」となっていますが、これは一般的な用 語の用法と異なっているので問題です。普通、「ゲートウェイ」と言えば、何 らかを中継する装置ですが、ここでは「何をどこからどこへ中継するのか」が 書かれていないため、よく分かりません。
5W1H が明確かを、それぞれチェックします。ここでも最初の文を見てみます。
(リング型 P2P-VPN に帰属する) ノードをゲートウェイと呼ぶ。
目的語 述語WHEN は「いつ」が一意に決まらないので問題です。「本稿では……」とか 「以下の説明では……」等の限定句を追加したほうがいいでしょう。
WHO は R3 で指摘したように主語が特定できないので問題です。「本稿で は……」とか「以下の説明では……」等の限定句を追加して、主語が「我々」 であることを明確にしたほうがいいでしょう。
WHERE は「どこで」が一意に決まらないので問題です。「本稿では……」とか 「以下の説明では……」等の限定句を追加したほうがいいでしょう。
WHY も「なぜ」が一意に決まらないので問題です。「簡単のため……」等の説 明を追加したほうがいいでしょう。
HOW は、述語が単純 (……と呼ぶ) なため問題ありません。
リング型 P2P-VPN に帰属するノードをゲートウェイと呼び、
ゲートウェイは配下に通信を行うユーザ端末を持つ。この文章では口語的な表現を用いていないので問題ありません。
ただし、「持つ」は万能動詞で意味があいまいなため、より具体的な単語に置 き換えたほうがいいでしょう。「ちょっと表現が堅いかな?」と思うくらいが 丁度いいようです。
リング型 P2P-VPN に帰属するノードをゲートウェイと呼び、
ゲートウェイは配下に通信を行うユーザ端末を持つ。「通信を行う」が冗長です。単に「通信する」としても意味が変わらないので、 こういう場合はできるだけ簡潔な表現を使います。
例えば、「測定を行う」、「測定方法について議論する」、「測定方法に関し て説明する」のような表現は使いません。より簡潔な表現である、「測定す る」、「測定方法を議論する」、「測定方法を説明する」を使います。
リング型 P2P-VPN のデータの転送機能について述べる。本章では、まず、リング型 P2P-VPN の基本的なデータ転送機能を説明する。
リング型 P2P-VPN に帰属するノードをゲートウェイと呼び、
ゲートウェイは配下に通信を行うユーザ端末を持つ。以下では、リング型 P2P-VPN に参加しているノードを、「VPN ゲートウェイ」 と呼ぶ。VPN ゲートウェイには、複数のエンドホストが接続されている。これ らのエンドホストは、接続されている VPN ゲートウェイを介して、他のエン ドホストと通信する。
各ゲートウェイは連続する片方向の IPsec トンネルで接続され、
全体としてリング型のトポロジを構成している。各 VPN ゲートウェイは、それぞれ 2 本の IPsec トンネルによって、他の VPN ゲートウェイと接続されている。このため、リング型 P2P-VPN は論理的 にリング型のトポロジを構成する。
通信を行いたい端末は、
まず自身が所属するゲートウェイに対してデータを送信する。あるエンドホスト A が、他の VPN ゲートウェイに接続されているエンドホス ト B とどのように通信するのかを説明する。まず、エンドホスト A が送出 したパケットは、エンドホスト A が接続されている VPN ゲートウェイにすべ て転送される。VPN ゲートウェイは、受信したパケットを、IPsec トンネルを 用いて、次の VPN ゲートウェイに転送する。
配下からデータを受信したゲートウェイは、
IPsec トンネルを通して前方のゲートウェイにデータを送出する。パケットを受信した VPN ゲートウェイは、この VPN ゲートウェイにエンドホ スト B が接続されていれば、受信したパケットをエンドホスト B に転送する。 一方、この VPN ゲートウェイにエンドホスト B が接続されていなければ、受 信したパケットを、IPsec トンネルを用いて、次の VPN ゲートウェイに転送 する。