-*- 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:52 oosaki Exp ohsaki $
この文章では、jcorrect という日本語文書校正ツールを用いて、どのように 技術文書を校正すれば良いかを説明します。「正しい技術文章作成のためのヒ ント」では、どのように正しい技術文書を書けば良いかを説明しました。そこ では、実例を挙げながら、技術文書の間違いをどのように見つければ良いのか、 見つけた間違いをどのように修正すれば良いのかを説明しました。
正しい技術文章作成のためのヒント (草稿)
http://www.lsnl.jp/~ohsaki/research/tips-japanese/しかし、「紹介されている例が間違っていることは分かるけれど、自分の書い た文章の間違いを見つけることができない」という声を聞きます。そこで、日 本語文書校正ツール jcorrect を用いて、技術文書の間違いを見つける方法を 説明します。
jcorrect は、形態素解析および係受け解析の結果を利用しているだけなので、 そもそも jcorrect の解析結果が間違っている可能性もあります。また、もち ろん jcorrect を使って検出できる間違いは、ごく少数にすぎません。あくま で、jcorrect は、技術文書を校正する補助的なツールとして使ってください。
jcorrect は、形態素解析 / 係受け解析ソフトウェアである、cabocha の解析 結果を利用して、日本語文章の校正を補助するツールです。jcorrect を実行 するためには、Perl バージョン 5 および cabocha が必要です。
CaboCha/南瓜: Yet Another Japanese Dependency Structure Analyzer
http://chasen.org/~taku/software/cabocha/cabocha は、日本語コーパスと SVM (Support Vector Machines) を利用した、 形態素解析 / 係受け解析ソフトウェアです。cabocha の作者によれば、係受 け解析の解析精度は約 90% だそうです。ですので、(cabocha の解析結果をそ のまま利用している) jcorrect の解析精度も当然約 90% になります。「解析 精度が 90% 程度では実用にならないのでは?」と思われるかもしれませんが、 以下のような理由により、日本語文書の校正ツールとして十分実用的に使うこ とが可能です。
「正しい技術文章作成のためのヒント」では、技術文章にとって、特に以下の 3 点が重要であると説明しました。
厳密であること (論理的に正しく、一意に解釈できること)
簡潔であること (複数の表現があれば、最も簡潔なものを使うこと)
読み易いこと (思考の流れを中断しないこと)
技術文書は簡潔であることが重要です。このため、正しい技術文書は「コン ピュータにとって形態素解析や係受け解析がしやすい文書のはず」とも言えま す。このため、jcorrect (cabocha) によって正しく係受け解析される文章を 書けば、それは自然と正しい技術文書になっているはずです。
なお、jcorrect の最新版は以下のページから入手できます。
jcorrect --- A simple Japanese grammer checker
http://www.lsnl.jp/~ohsaki/software/perl/jcorrectWeb ページから利用できるインターフェースは以下にあります
jcorrect --- A simple Japanese grammer checker [Web interface]
http://www.lsnl.jp/cgi-bin/jcorrect簡単なものですが、Emacs から jcorrect を対話的に起動するために、私が使 用している Elisp を公開しておきます。
http://www.lsnl.jp/~ohsaki/software/elisp/jcorrect.el「正しい技術文章作成のためのヒント」では、以下のような、技術文書作成の ための 6 つのルールを説明しました。
jcorrect で検出できる間違いは、R1 〜 R3 に反している間違いと、R4 〜 R6 に反している間違いの一部です。
R1 〜 R3 は、文章の論理的な構造が正しいかどうかに関するルールなので、 係受けの関係を解析することによって検出することが可能です。一方、R4 〜 R6 は、文章の意味を解析しなければ間違いが検出できません。jcorrect では、 単純なパターンマッチによって、R4 〜 R6 の間違いが「ありそう」な箇所に ついて警告が表示されます。ただし、R4 〜 R6 に反する間違いの検出精度は 非常に低いので注意してください。
ここで、私がこれまでに指導した学部 4 年生が作成した文章を紹介します。 これは、「正しい技術文章作成のためのヒント」で取り上げたものと同じです。
$ cat sample.txt
リング型 P2P-VPN のデータの転送機能について述べる。リング型 P2P-VPN に
帰属するノードをゲートウェイと呼び、ゲートウェイは配下に通信を行うユー
ザ端末を持つ。各ゲートウェイは連続する片方向の IPsec トンネルで接続さ
れ、全体としてリング型のトポロジを構成している。通信を行いたい端末は、
まず自身が所属するゲートウェイに対してデータを送信する。配下からデータ
を受信したゲートウェイは、IPsec トンネルを通して前方のゲートウェイにデー
タを送出する。以下では、実際に jcorrect を使用して、技術文書の間違いをどのように見つ ければ良いかを説明します。
jcorrect は、標準入力からテキストを読み込み、解析結果を標準出力に書き 出します。まず、例文に対して、jcorrect を実行してみます。
$ jcorrect <sample.txt
リング型P2P-VPNのデータの転送機能について述べる。
リング型P2P-VPNの-D
データの-D
転送機能について-D
述べる。
1: **** misssing subject for `述べる'
1: **** avoid using `について' (instead use `を')
1: check meaning of `転送機能について -> 述べる'
1: check meaning of `データの -> 転送機能について'
1: check meaning of `リング型の -> データの'
リング型P2P-VPNに帰属するノードをゲートウェイと呼び、
ゲートウェイは配下に通信を行うユーザ端末を持つ。
リング型P2P-VPNに-D
帰属する-D
ノードを---D
ゲートウェイと-D
呼び、-----------D
ゲートウェイは---------D
配下に---D |
通信を-D |
行う-D |
ユーザ端末を-D
持つ。
1: check meaning of `呼び|ゲートウェイは|ユーザ端末を -> 持つ'
1: check meaning of `行う -> ユーザ端末を'
1: check meaning of `配下に|通信を -> 行う'
1: **** reversed word order `配下に -> 通信を'
1: check meaning of `ノードを|ゲートウェイと -> 呼び'
1: check meaning of `帰属する -> ノードを'
1: check meaning of `リング型に -> 帰属する'
各ゲートウェイは連続する片方向のIPsecトンネルで接続され、
全体としてリング型のトポロジを構成している。
各ゲートウェイは-------D
連続する-D |
片方向の-D |
IPsecトンネルで-D
接続され、-------D
全体として-----D
リング型の-D |
トポロジを-D
構成している。
3: **** avoid using `している' (instead use `する')
3: check meaning of `接続され|全体として|を -> 構成している'
3: check meaning of `リング型の -> を'
3: check meaning of `各ゲートウェイは|IPsecトンネルで -> 接続され'
3: check meaning of `片方向の -> IPsecトンネルで'
3: check meaning of `連続する -> 片方向の'
通信を行いたい端末は、
まず自身が所属するゲートウェイに対してデータを送信する。
通信を-D
行いたい-D
端末は、-----------D
まず---D |
自身が-D |
所属する-D |
ゲートウェイに対して---D
データを-D
送信する。
5: check meaning of `端末は|ゲートウェイに対して|データを -> 送信する'
5: check meaning of `所属する -> ゲートウェイに対して'
5: check meaning of `まず|自身が -> 所属する'
5: check meaning of `行いたい -> 端末は'
5: check meaning of `通信を -> 行いたい'
配下からデータを受信したゲートウェイは、
IPsecトンネルを通して前方のゲートウェイにデータを送出する。
配下から---D
データを-D
受信した-D
ゲートウェイは、---------D
IPsecトンネルを通して-------D
前方の-D |
ゲートウェイに---D
データを-D
送出する。
7: check meaning of `ゲートウェイは|IPsecトンネルを通して|ゲートウェイに|データを -> 送出する'
7: **** reversed word order `ゲートウェイに -> データを'
7: check meaning of `前方の -> ゲートウェイに'
7: check meaning of `受信した -> ゲートウェイは'
7: check meaning of `配下から|データを -> 受信した'
7: **** reversed word order `配下から -> データを'jcorrect の出力結果は、入力されたテキストのそれぞれの行に対して、
原文
係受け解析の結果
チェックリストが繰り返し表示されます。例えば、入力ファイルの一行目である、
リング型 P2P-VPN のデータの転送機能について述べる。に対応する解析結果は以下のものです。
リング型P2P-VPNのデータの転送機能について述べる。
リング型P2P-VPNの-D
データの-D
転送機能について-D
述べる。
1: **** misssing subject for `述べる'
1: **** avoid using `について' (instead use `を')
1: check meaning of `転送機能について -> 述べる'
1: check meaning of `データの -> 転送機能について'
1: check meaning of `リング型の -> データの'では、実際に jcorrect の解析結果を見ながら、例文の間違いを見つけてゆき ましょう。
リング型P2P-VPNのデータの転送機能について述べる。
リング型P2P-VPNの-D
データの-D
転送機能について-D
述べる。
1: **** misssing subject for `述べる'
1: **** avoid using `について' (instead use `を')
1: check meaning of `転送機能について -> 述べる'
1: check meaning of `データの -> 転送機能について'
1: check meaning of `リング型の -> データの'jcorrect では、cabocha の解析結果を利用しており、(解析された) 係受けの 関係がツリー状に表示されています。
この例では、
「リング型P2P-VPNの」が「データの」を修飾している
「データの」が「転送機能について」を修飾している
「転送機能について」が「述べる」を修飾していることを示しています。
jcorrect が表示しているチェックリストのうち、「****」が表示されている 箇所はエラーメッセージを、それ以外の箇所は警告メッセージを意味していま す。ツリー状に表示された係受け解析の結果を見ながら、各チェックリストを 見てゆきます。
1: **** misssing subject for `述べる'これは、「述べる」の主語がないというエラーを示しています。
1: **** avoid using `について' (instead use `を')これは、「……について」は冗長であるためエラーを示しています。代わりに「…… を」という表現を使うよう指示しています。
1: check meaning of `転送機能について -> 述べる'
1: check meaning of `データの -> 転送機能について'
1: check meaning of `リング型の -> データの'これらは、係受けの関係が論理的に正しいかを調べるためのチェックリストで す。例えば、
「リング型P2P-VPNの」が「データの」を修飾しているという文章の骨格は、
「リング型の」が「データの」を修飾しているですので、
1: check meaning of `リング型の -> データの'は、これが論理的に正しいかチェックせよ、という警告メッセージです。意味 を考えれば、
1: check meaning of `転送機能について -> 述べる'
1: check meaning of `データの -> 転送機能について'の二つは正しいけれども、
1: check meaning of `リング型の -> データの'は間違っている、とうことが分かります (「リング型のデータ」が何のことか 分かりません)。次の文章の解析結果を見てみましょう。
リング型P2P-VPNに帰属するノードをゲートウェイと呼び、
ゲートウェイは配下に通信を行うユーザ端末を持つ。
リング型P2P-VPNに-D
帰属する-D
ノードを---D
ゲートウェイと-D
呼び、-----------D
ゲートウェイは---------D
配下に---D |
通信を-D |
行う-D |
ユーザ端末を-D
持つ。
1: check meaning of `呼び|ゲートウェイは|ユーザ端末を -> 持つ'
1: check meaning of `行う -> ユーザ端末を'
1: check meaning of `配下に|通信を -> 行う'
1: **** reversed word order `配下に -> 通信を'
1: check meaning of `ノードを|ゲートウェイと -> 呼び'
1: check meaning of `帰属する -> ノードを'
1: check meaning of `リング型に -> 帰属する'まず、ツリー状に表示された係受け解析を見ると、この文章が複雑な係受け構 造を持っていることが分かります。この例では、係受けの深さが最大で 4 (リ ング型 P2P-VPN に→帰属する→ノードを→呼び→持つ) と大きな値になって います。もちろん例外はありますが、係受けの深さを 3 程度に抑えましょう。
また、木の構造が偏っている (バランスしていない) こともわかります。これ は係受けの深さが大きいことも影響しています。正しい技術文章に jcorrect を実行してみて、木の構造がどの程度バランスすべきかを見てみると良いでしょ う。
次に、jcorrect のチェックリストを見てゆきましょう。
1: check meaning of `呼び|ゲートウェイは|ユーザ端末を -> 持つ'この例では、「呼び」、「ゲートウェイは」、「ユーザ端末を」がそれぞれ 「持つ。」を修飾しています。このため、上記の警告メッセージは、
呼び -> 持つ
ゲートウェイは -> 持つ
ユーザ端末を -> 持つがすべて論理的に正しいかチェックせよ、という意味です。意味を考えれば、 「ゲートウェイは」→「持つ」および「ユーザ端末を」→「持つ」は意味が通 じますが、「呼び」→「持つ」は意味が通じないので、この部分が間違ってい ることが分かります。
1: check meaning of `行う -> ユーザ端末を'これも意味が通じませんので、この部分が間違っていることが分かります。
1: check meaning of `配下に|通信を -> 行う'「通信を」→「行う」は意味が通じますが、「配下に」→「行う」は意味が通 じませんので、この部分が間違っていることが分かります。
1: **** reversed word order `配下に -> 通信を'これは、語順に問題があるというエラーです。jcorrect では、「……が(は)…… を……から……に……する」という語順でなければエラーを表示します。語順 が入れ替わっていても、日本語としては間違いではありませんが、より分かり やすい技術文章とするため、この順番に従うことを推奨します。
なお、jcorrect は単純なパターンマッチによって語順をチェックしているた め、実際には問題がない場合にもエラーが表示されることがあるので注意して ください。
1: check meaning of `ノードを|ゲートウェイと -> 呼び'これは問題ありません。
1: check meaning of `帰属する -> ノードを'これも問題ありません。
1: check meaning of `リング型に -> 帰属する'「リング型に」→「帰属する」は意味が通じませんので、この部分が間違って いることが分かります。
以下、同様にチェックしてみてください。jcorrect の結果をチェックするのは、 かなり集中力が必要な作業です。普段から、少しずつ、こまめに jcorrect の 結果をチェックする習慣をつけてください。
各ゲートウェイは連続する片方向のIPsecトンネルで接続され、
全体としてリング型のトポロジを構成している。
各ゲートウェイは-------D
連続する-D |
片方向の-D |
IPsecトンネルで-D
接続され、-------D
全体として-----D
リング型の-D |
トポロジを-D
構成している。
3: **** avoid using `している' (instead use `する')
3: check meaning of `接続され|全体として|を -> 構成している'
3: check meaning of `リング型の -> を'
3: check meaning of `各ゲートウェイは|IPsecトンネルで -> 接続され'
3: check meaning of `片方向の -> IPsecトンネルで'
3: check meaning of `連続する -> 片方向の'
通信を行いたい端末は、
まず自身が所属するゲートウェイに対してデータを送信する。
通信を-D
行いたい-D
端末は、-----------D
まず---D |
自身が-D |
所属する-D |
ゲートウェイに対して---D
データを-D
送信する。
5: check meaning of `端末は|ゲートウェイに対して|データを -> 送信する'
5: check meaning of `所属する -> ゲートウェイに対して'
5: check meaning of `まず|自身が -> 所属する'
5: check meaning of `行いたい -> 端末は'
5: check meaning of `通信を -> 行いたい'
配下からデータを受信したゲートウェイは、
IPsecトンネルを通して前方のゲートウェイにデータを送出する。
配下から---D
データを-D
受信した-D
ゲートウェイは、---------D
IPsecトンネルを通して-------D
前方の-D |
ゲートウェイに---D
データを-D
送出する。
7: check meaning of `ゲートウェイは|IPsecトンネルを通して|ゲートウェイに|データを -> 送出する'
7: **** reversed word order `ゲートウェイに -> データを'
7: check meaning of `前方の -> ゲートウェイに'
7: check meaning of `受信した -> ゲートウェイは'
7: check meaning of `配下から|データを -> 受信した'
7: **** reversed word order `配下から -> データを'