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

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

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

類似節

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

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

これは類似する節をひとつにマージするシグナルといえます。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を追加すると,アルファベット単語の前後にスペースが無い場合にエラーを出力します。

※3
本連載ではアルファベット単語の前後にスペースを入れないという規約にもとづいて執筆しています。

この記事の執筆に使用した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がはじめにフォーカスしたいのはあきらかな誤りやフォーマット異常の検出だからです。

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

日本語の調

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

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

著者プロフィール

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

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