正しい技術文章作成のためのヒント

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

Download Report