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

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

今回は、文書執筆で一般的に気をつけるべきと言われている点について解説します。これらの気をつけるべき点を、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が例外単語として登録されています。

表現に関する機能

RedPenは文書の表現に関する規約を強制する機能をいくつか提供します。

不正な表現

文書を書くときには同じ意味を持つ専門用語が複数使われるべきではありません。たとえば次の文には問題があります。

分散システムの各インスタンスには役割が付与される場合がある。付与される役割は予め設定ファイルで決められることが多いが、動的に変化する分散型システムも存在する。

上の例では分散システム分散型システムという同一の内容を示すふたつの専門用語が使用されています[1]⁠。同一の意味を持つ複数の専門用語が存在すると読者に不安感をあたえるため、ひとつの表現に統一するのが望ましいです。

RedPenは不正な表現を検知する機能をいくつかInvalidWordInvalidExpressionSuggestExpression提供します。これらの機能はあらかじめ登録された単語や表現が文中に現れた際にエラーを出力します。

InvalidWord機能は不正な単語が現れた際にエラーを出力します。つまり、トークナイザ(形態素解析器)で抽出された単語にたいしてチェックします。英語やヨーロッパ系の言語の単語分割はスペースで区切るだけなので単純です。しかし日本語のように単語の区切りがあいまいな言語では、単語が誤って抽出されてしまうおそれがあります。そのため日本語のように明示的に単語が分かれていない言語では、InvalidWord機能が期待したとおりに動作しないおそれがあります。

対象文書が日本語の場合にはInvalidExpressionとSuggestExpressionが利用できます。両者はともに入力文に不正な(単語区切りされていない)表現が出現したときにエラーを出力します。SuggestExpressionはエラーの内容にこの表現を利用したほうが望ましいというサジェストが含まれます。SuggestExpressionでサジェストされる表現は設定に記述する必要あるので少々面倒です。通常はInvalidExpressionで十分でしょう。

InvalidExpressionは不正表現のデフォルト辞書を持ちます。デフォルト辞書が十分ない場合にはユーザは辞書を拡張できます。

注:
上記最後の文は3ページ目でも引用として登場します。
次の例は、InvalidExpressionに不正な表現"嘘でしょ"、"マジで"を追加した設定となります。
<validators>
    <validator name="InvalidExpression">
      <property name="嘘でしょ,マジで" >
    </validator>
</validators>

省略形の利用

省略形("Let's" や "we'll")はフォーマルな技術文書や論文では使用してはなりません。RedPenは省略形の使用という問題にたいしてContraction機能を提供します。Contraction機能は英語文書内で省略形の単語が存在した場合にエラーを出力します。Contraction機能を追加した設定例は次の通りです。

<validators>
    <validator name="Contraction" />
</validators>

スペースに関する機能

英語文書では単語だけでなくシンボルの前後に半角スペースを入れます。英語だけでなく日本語文書でも、半角シンボルを利用する場合には半角スペースをシンボルの前後(主に後ろ)に入れる規約が一般的です。特殊シンボル(括弧やピリオド)の後に半角スペースがないと、フォントによって読みづらく感じることがあるためです。私も学生時代書いた文書は半角シンボルを利用していたため、シンボルの前後にスペースを入れてました。

RedPenはシンボルの前後スペースの規約を強制する機能、SpaceWithSymbolを提供します。しかし、デフォルトの日本語のシンボル設定は全角文字の利用を想定してます。そのためSpaceWithSymbolは日本語文書にたいしてエラーを出力しません。

ユーザが半角シンボルを利用し、SpaceWithSymbolを動作させるには文字設定を変更する必要があります。具体的にはsymbolブロックを追加してデフォルトの設定を上書きします。symbolブロックのアトリビュートbefore-space=trueはシンボルの前に半角スペースが必要であることを示します。同様にafter-space=trueはシンボルの後ろに半角スペースが必要なことを示します。

次の例では、いくつかのシンボルについて前後のスペースに関する設定を変更しています。

<redpen-conf lang="ja">
    <validators>
        <validator name="SpaceWithSymbol" />
    </validators>
    <symbols>
        <symbol name="FULL_STOP" value="." after-space="true"/>
        <symbol name="COMMA" value="," after-space="true"/>
        <symbol name="EXCLAMATION_MARK" value="!" after-space="true"/>
        <symbol name="QUESTION_MARK" value="?" after-space="true"/>
        <symbol name="LEFT_PARENTHESIS" value="(" before-space="true"/>
        <symbol name="RIGHT_PARENTHESIS" value=")" after-space="true"/>
    <symbols>
 </redpen-conf>

単語の複数回利用

同一の単語が一文の中で複数回使われていると、悪い印象をもたれるおそれがあります。たとえば以下の文は本稿の前節のために書かれた文です。残念ながら"設定"という単語が2回も利用され、少々冗長な印象を受けます。

日本語のデフォルトの設定では全角シンボルを利用する設定になっているので、SpaceWithSymbolは日本語文書にたいしてエラーを出力しません。

そこで、本稿の最終検査で次のように書きなおしました。

デフォルトの日本語のシンボル設定は全角文字の利用を想定してます。そのためSpaceWithSymbolは日本語文書にたいしてエラーを出力しません。

RedPenが提供するDoubledWord機能は1文に複数回単語が出現した際にはエラーを出力します。ただし文書の主題にあたるキーワードは1文で複数回利用されることは当然あります。

たとえば、本稿でもRedPenという単語が1文で2回現れている文が存在します。そこでDoubledWord機能は例外単語列をサポートしています。例外単語列に登録された単語は複数回出現してもエラーは出力されません。以下、本連載の第2回を執筆する際に使用したDoubledWord機能の設定例です。

<validator name="DoubledWord">
  <property name="list" value="redpen,文書,機能,文,長,シンボル"/>
</validator>

上の例では例外単語列に"redpen"、"文書"などの単語が追加されています。これらの単語は文書の主題ですので、1文で2回以上利用されることを許しました。

単語の連続使用

前節で解説したように1文で複数回同一単語が利用されていても、その単語が主トピックであったり助詞であれば問題ありません。しかし同一の単語が連続で現れた場合は、まちがいなく問題です。

そこでRedPenはDoubledWord機能とは別にSuccessiveWord機能を提供します。SuccessiveWord機能は、DoubledWord機能のデフォルト辞書やユーザが追加した例外列に存在する単語であってもエラーを出力します。実はこのSuccessiveWord機能は私のお気に入りで[2]⁠、何度も助けてもらいました。

類似節

プログラムでは同じようなコードブロックを複数回書いているときには、いわゆるいやな臭いがします。いやな臭いはリファクタリングの合図です。はじめにブロックを関数もしくはクラスとして抽出し、次に該当箇所を関数(メソッド)呼び出しに置き換えます。

長い文書を書くと、プログラムと同様に同じような内容の節が複数現れてくることがあります。同じような内容が文書内に複数存在してしまうと、将来修正の必要があった場合にはすべての箇所を修正しなければなりません。そのため、修正の手間がかかりますし、修正し忘れが簡単に発生します。

これは類似する節をひとつにマージするシグナルといえます。RedPenではDuplicatedSection機能を提供しています。DuplicatedSection機能は著しく似た内容をもつ節ペアを検出してくれます。DuplicatedSection機能からエラーが報告された場合、はじめに節を一箇所にマージします。次に各該当箇所からリンクを張ることで内容をひとつに集約できます。

英語の文末

英語の文末で気をつけないといけないにクォーテーションマークとピリオドの位置があります。アメリカ英語の文末規約では、ピリオドの後にクォーテーションマークがきます。次の例がその文末表現です。

In this article, we'll call a computer server that works as a member of a cluster an "instance."

RedPenで文末の表現を検査するにはEndOfSentenceをvalidatorsに追加します。

<validators>
    <validator name="EndOfSentence" />
</validators>

日本語文書内のアルファベット単語

日本語文書でも外来単語を記述する際に、アルファベットをそのまま利用することがあります。このような場合、⁠英単語の前後に半角スペースを入れる⁠という規約にもとづいて文書を作成することがあります。

たとえば、次の文ではHadoopという単語の前後にスペースを入れています[3]⁠。

分散処理システム Hadoop は大量のデータを処理できる。

半角スペースをアルファベット単語の前後に入れる、入れないは個人(もしくは所属組織)の判断で、どちらでも問題ありません。しかし両規約がまじってしまうと文書の品質が疑われてしまいます。

この問題にたいしてRedPenはSpaceBetweenAlphabeticalWord機能を提供します。設定にSpaceBetweenAlphabeticalWordを追加すると、アルファベット単語の前後にスペースが無い場合にエラーを出力します。

この記事の執筆に使用したRedPenの設定

今回の記事の原稿ももちろんRedPenで検査をしています。その際利用したRedPenの設定ファイルは次の通りです。

<redpen-conf lang="ja">
    <validators>
        <validator name="SentenceLength">
            <property name="max_len" value="100"/>
        </validator>
        <validator name="InvalidSymbol" />
        <validator name="CommaNumber" />
        <validator name="InvalidExpression">
            <property name="list" value="文章,プログラマ,検査ツール,幾つか,合わせて,対して,ポイント"/>
        </validator>
        <validator name="KatakanaEndHyphen"/>
        <validator name="KatakanaSpellCheck"/>
        <validator name="SectionLength">
            <property name="max_num" value="1500"/>
        </validator>
        <validator name="ParagraphNumber">
            <property name="max_num" value="10"/>
        </validator>
        <validator name="DoubledWord">
            <property name="list" value="redpen,文書,機能,文,長,シンボル"/>
        </validator>
        <validator name="SymbolWithSpace" />
        <validator name="SuccessiveWord" />
        <!-- <validator name="SpaceBetweenAlphabeticalWord" /> -->
    </validators>
</redpen-conf>

SpaceBetweenAlphabeticalWordがコメントアウトされているのは、技評の規約ではアルファベット単語の前後にはスペースを入れないためです。InvalidExpressionの設定では、"合わせて"と"幾つか"を追加しました。これらの表現をひらがなで統一したいと考えたためです。ひらがなにしたいと考えたのは文書内で漢字が多すぎると硬い印象を与えてしまうためです。

また、"ポイント"もInvalidExpressionに追加しました。当時の原稿には"点"と"ポイント"が混在してしまい見苦しかったため、すべて"点"で統一するために追加しました。一度設定に追加すると、後日"ポイント"と記述するたびにエラーが報告されるようになるので便利です。

実は今回の最終稿でも20件ほどのエラーが報告されています。たとえば、本稿に含まれている次の文には問題が残ったままです。

デフォルト辞書が十分ない場合にはユーザは辞書を拡張できます。

単語"辞書"が1文に2回出現しています。表現を変更することも考えたのですが、大きな問題でないと判断しそのままにしています。今ふりかえってみると、"要素を追加できます"と変更してもよかったかと考えています。

将来的にRedPenに指定した箇所のエラーを抑制する仕組みを導入したいと考えています。利用のイメージとしては、節やパラグラフの上に抑制するエラーの種類を書いておくと該当箇所のエラーは無視されるというものです。この仕組みが導入されることで、理由があって(チームの合意がとれて⁠⁠、無視したい箇所のエラーを抑制できるようになる予定です。

現状対応できていない箇所と今後の機能追加

現在提供されている機能は、文字もしくは単語ベースの単純な機能ほとんどです。単純な機能だけを提供しているのは、RedPenがはじめにフォーカスしたいのはあきらかな誤りやフォーマット異常の検出だからです。

とはいえ除々にではありますが、言語の情報を利用した機能を順次提供する予定です。直近では次の機能を提供する予定です。

日本語の調

日本語文書では大きく分けてふたつの調、ですます調である調が存在します。どちらを使っても問題ないのですが、混じってしまうと悪い印象を与えます。本機能は文末の表現が混じってしまう場合にエラーを報告します。

語順(品詞、単語)
品詞や単語の連続で不的確なものを検出します。たとえば、"動詞"+"を(格助詞)"という語順はあきらかな誤りです。本機能は明らかな誤りとなる語順をルールとして登録しておき、出現した際にエラーを出力します。

おすすめ記事

記事・ニュース一覧