RedPenを使って技術文書を手軽に校正しよう

第3回 文書執筆で気をつける点とRedPenを利用した予防方法

この記事を読むのに必要な時間:およそ 6.5 分

今回は,文書執筆で一般的に気をつけるべきと言われている点について解説します。これらの気をつけるべき点を,RedPenを利用してどのように検知するかについて解説します。本稿の最後に、連載で実際に使用したRedPenの設定と簡単な解説を紹介します。

文書執筆に関する書籍

文書を書く上で気をつける点(ポイント)は一般的に知られており,多くの文書執筆に関する書籍も出版されています。日本で文書指南書の決定版といえば,木下是雄先生の理科系の作文技術ではないでしょうか。私も学生時代にこの本を読んで勉強させてきただきました。

英語でも決定版と言える本があります。The Elements of Styleという100年前に書かれた本で,英語文書の執筆で気をつける点が簡潔に整理されています。

今回解説するトピックの多くは文書執筆に関する書籍で共通して記載されている内容です。

文書の執筆で気をつける点とRedPenの設定

本節では,文書の執筆で気をつける点について紹介します。その際,気をつける点を検知するためのRedPenの設定もあわせて解説します。

長さに関する規約

RedPenは長さに関する規約を強制する機能をいくつか提供しています。

文長

文書執筆に関する本にすべてに共通して述べられているのは文は短くという点です。私が文書の校正をお手伝いするときには,かならず文長の検査からはじめます。文長が重要なのは,文は長いほど理解が難しくなるからです。自分の場合,余程のことがない限り1文は100文字以内におさえています。

文長をおさえるために,RedPenではSentenceLength機能を提供しています。SentenceLengthは指定された文長(文字数)を超える文にたいしてエラーを出力します。設定例は次の通りです。SentenceLength機能はmax_lenプロパティを持ち,文の最大長を設定できます。この例では文の最大長を120に設定しています。

<validators>
    <validator name="SentenceLength>
        <property name="max_len" value="120"/>
    </validator>
</validators>
文以外の長さ

RedPenでは文長以外に節,パラグラフの最大長を強制する機能を持っています。節の長さがSectionLength機能で,パラグラフ長がParagrahLengthです。これらの機能は短い文書では必要ないのですが,長い文書を書くときに追加しておくと,節やパラグラフが知らないあいだに長くなってしまう不具合を教えてくれます。

カンマの数

カンマは適切なタイミングで付与すると読者が文を理解するのに役立ちますが,あまり多いと逆に読みづらくなってしまいます。RedPenの設定ファイルにCommaNumber機能を追加すると,カンマが多すぎる文が発見された場合にエラーを出力してくれます。

シンボルの統一

句読点や括弧などの利用するシンボルが統一されていないと,読者に文書の品質について疑われてしまいます。しかし残念ながら,特に複数人で文書を執筆している場合にはシンボルの非統一が簡単におこります。さらにシンボルは類似した形を持っているため,人目で確認してもなかなか発見できない場合があります。

これらシンボルの統一のために,RedPenではシンボルの非統一を検知するInvalidSymbol機能を提供しています。InvalidSymbolは不正なシンボルが発見された時にエラーを出力します。RedPenは言語ごとにデフォルトのシンボルテーブルを持っています。テーブルは利用可能なシンボルと不正なシンボル群InvalidCharsのペアを持っています。デフォルトシンボルテーブルについては日本語のシンボル設定を参照してください。たとえば日本語文書の句点FULL_STOPはデフォルトで"。"に設定されており,句点に対する不正なシンボルinvalid_charsとして".","."が登録されています。

シンボル設定の変更

デフォルトの設定を上書きしてシンボルの非統一を検知してみましょう。必要な記述は利用するシンボルと使用してはいけないシンボル(複数可)ペアをsymbolsブロックに追加するだけです。もしユーザが句点(FULL_STOP)として"."を指定して,かつ"."と"。"を不正なシンボルとして登録するには次の設定を加えます。

<redpen-conf lang="ja">
    <validators>
        <validator name="InvalidSymbol" />
    </validators>
    <symbols>
        <symbol name="FULL_STOP" value="." invalid_chars="。."/>
    </symbols>
 </redpen-conf>

上の例をみるとわかるように,symbolsブロックの中にFULL_STOPというsymbolを追加して,不正な文字invalid_charsもあわせて登録しています。他にもシンボルの設定を変更したい場合には,symbolsブロックにsymbolをひとつずつ追加します。

スペルチェック

RedPenは単語のスペルチェックに関する機能をいくつか提供しています。

カタカナ

カタカナ単語のスペリングに関してRedPenはふたつの機能を提供しています。ひとつはKatakanaSpellCheck機能です。KataKanaSpellCheckはカタカナ単語のスペリングを検査します。もうひとつはKatakanaEndHyphen機能で,JIS Z831にもとづいてカタカナ単語の末尾長音の正しさを検査します。

例えば,文内にファクトリーという単語があったとき,KatakanaEndHyphen機能は末尾長音が不要とエラーを出力します。エラーを抑制するには,ファクトリと不要な長音を削除する必要があります。

RedPenでスペルチェックに関する機能を追加する設定は次の通りです。

<validators>
    <validator name="KatakanaSpellCheck" />
    <validator name="KatakanaEndHyphen" />
</validators>
英語

RedPenはカタカナ以外に英単語のスペルチェック機能Spellingを提供しています。Spelling機能は半角スペースで区切られた単語にたいしてのみ動作する点に注意してください。

Spelling機能は辞書をベースにスペルチェックをおこないます。そのため辞書に収録されていないような専門用語が出現するとエラーとなってしまうおそれがあります。そのような場合にはlistプロパティに例外の単語列(エクセプションリスト)を追加してください。

Spelling機能とエクセプションリストの例は次の通りです。

<validators>
    <validator name="Spelling">
         <property name="list" value="Hadoop,SVM"/>
    </validator>
</validators>

上の例ではHadoopとSVMが例外単語として登録されています。

著者プロフィール

伊藤敬彦(いとうたかひこ)

ソフトウェアエンジニア。専門はデータマイニングと情報検索だが,他にも色々やってみたいと感じている。

コメント

コメントの記入