はじめに
本稿では技術文書の指南書で解説されている文書の問題点を RedPen で発見する方法について解説します。紹介する文書の問題点は以下の指南書で解説されている内容です（執筆者の敬称略）。
上記の指南書で解説されている問題点の多くはシンプルです。しかし残念ながら、指南書で解説されている文書の問題点はプログラムのコーディング規約ほど広く認知されていません。さらに問題点に注意しながら文書を執筆するのは簡単ではありません。たとえば、textlint を開発されている @azu_reさん は以下のように述べています。
あなたはIMEほど記憶能力が高くないが、IMEはあなたほど賢くない。
— azu (@azu_re) 2016年5月22日
なので二つで作った文章には綻びが生じやすい。
それをtextlintやRedPenなどの第三者が見つける。
上で述べられているように、文書の継続的な検査には textlint や RedPen のような文書の自動検査ツールが役立ちます。両ツールとも専門家の完全なレビューではありませんし、外に出す文書であれば専門家の検査は欠かせません。それでも両ツールは専門家にレビューしてもらうまでの、一次検査としては機能すると考えています。
本稿の textlint 版が、@azu_re さんによって記述されました。textlint をお使いの場合には、こちらの記事を参照してください。
ツールによる検査の利点
私がとある会社で働いていた時、多数の静的解析ツールを利用してコードを自動検査していました。検査する項目は潜在的なバグ発見、コーディング規約、リソースの消費や実行スピードにもおよびました。なぜ、こんなに自動検査をするのかと同僚にたずねた所、人が検査すると人間関係が悪くなるから自動でできる検査はすべて自動でやりたいと言われました。言っている意味がわからなかったので詳しく聞くと、信頼関係のない同僚間（人手）でレビューイングをすると人は相手が嫌がらせをしているのではと疑ってしまうが、ツールだとそのような心配がないので便利ということでした。
特に文書の問題点は、先に紹介したように、一般的に共有されていません。そのため、人手による文書のレビューはコードのレビュー以上に人間関係を悪くしてしまう恐れがあります。これに対して、自動検査ツールで結果を返すのは人ではなくツールですので執筆者は嫌がらせを疑う必要はありません。
本稿では指南書で解説されている文書の問題点と RedPen を利用して発見する方法をペアで解説します。指南書で解説されている問題点と RedPen の機能がペアで解説されると、利用者が RedPen からのエラーを受け入れやすいと考えました。
対象とする読者
本稿の対象は論文やマニュアルなどの技術文書を書く人です。本稿を読むにあたって特に専門的な知識は必要ありません。ただし、本稿の内容をより深く理解するために、前節で紹介した資料に目を通しておくのをおすすめします。また RedPen についての記事ですので、RedPen をインストール しておくとよいでしょう。本稿が対象とする RedPen のバージョンは 1.6 です。
指南書で紹介されている文書の問題点
以下、上記の指南書で解説されている文書の問題点と、RedPen を使って発見する方法について解説します。
文の長さ
「理科系の作文技術」の8章「わかりやすく簡潔な表現」を含め、数多くの文書執筆の指南書で「文は短く簡潔」に書くべきと言われています。長い文を理解するのには時間がかかりますし、そもそも読者が文を理解できない可能性があります。上記の執筆指南書ではありませんが、「技術文書の書き方」という資料では文は 100 文字以内にするべきと解説しています。
RedPen では文の長さに関する機能に、SentenceLength があります。SentenceLength は入力文書の中に長すぎる文（センテンス）が見つかるとエラーを出力します。また、私は文を短くする方法について「文が長すぎる問題とその対処」という記事を書きました。あわせて参考にしてください。
言葉の品性
技術文書では感情的な単語や、曖昧な単語など利用するべきではない単語があります。たとえば、「文章の書き方」の 17ページ目より「言葉の品性」の解説で利用するべきでない単語について紹介しています。
RedPen が提供する InvalidExpression は使用するべきでない単語が見つかるとエラーを出力します。ただし、InvalidWord 用の表現辞書は十分ではないので、各自気になる表現を追加してください。
冗長な表現
「文章の書き方」では「〜ことができる」や「〜を行う」を冗長な表現として紹介しています。「することができる」は有害と考えられる」 で紹介したようにスクリプトで冗長表現を検知するとよいでしょう。今後、RedPen 本体でも冗長表現を検知する機能を提供する予定です。
用語の揺らぎ
「文章の書き方」の6ページ、「言葉の揺れ」は、文書で使用する単語（用語）が揺れないようにとアドバイスしています。文書で利用される用語に揺らぎがあると、読者が内容を理解できなくなる恐れがあります。RedPen では、SuggestExpression という機能で用語の揺らぎに対処します。用語として使うべき単語と、単語の揺らぎのペアを登録していると、文書に単語の揺らぎが現れた時にエラーを出力します。
また、句読点などのシンボルも文書内で統一されていない場合があります。読みにくさには大きく影響はしませんが、見栄えが悪いので統一しましょう。この問題に対して RedPen ではシンボルの誤用を検知する InvalidSymbol を提供しています。
漢字とかな
「数学文書作法」の2.4章に「漢字とかな」という節があります。この節は漢字ではなく、ひらがなで記述する表現について解説しています。たとえば「然し」と、「しかし」を比べると、「しかし」と書の方がわかりやすい表現です。RedPen にはこの問題を扱う機能はありません。しかし、@kongou_ae さんが作成した redpen-validator の use-hiragana-and-kanji-properly.js はひらがなと漢字の使い分けを検査できます。
redpen-validator には他にもJTF（Japan Translation Federation）日本語標準スタイルガイドに基づいて文書を検査できるプラグイン（"常用漢字を使っているか"、"助数詞にともなう「か」の表記"）が豊富に用意されています。
アラビア数字と漢数字
「数学文書作法」の2.4章に「アラビア数字と漢数字」という節があります。この節では文書内の数値表現を統一するべきと書いています。日本語の数値表現にはアラビア数字（1つ、2つ、3つ）と、漢数字（一つ、二つ、三つ）があります。数値表現はどちらでも構いませんが、文書内ではどちらか一方のみを使うべきです。
RedPen の JapaneseNumberExpressionは数値表現のスタイルが一貫していない箇所を検出しエラーを出力します。
章節もアラビア数字と、漢数字で参照します。RedPen の JapaneseAnchorExpression は文書内で使用される章節参照の表現が統一されているかを検査します。
二重否定
二重否定を使用した文は読者の理解を阻害します。「数学文書作法」の 4.2節、「二重否定を避ける」では、二重否定を避ける理由について解説しています。RedPen では DoubleNegative という機能で二重否定の利用を検知します。ただし、実装が十分でないため検知しきれない事例があります。二重否定が検知できていない例が見つかったら RedPen の Issue に登録していただけますと助かります。
括弧の利用方法
「文章の書き方」の 25ページ目、「注釈と括弧」では必要でない括弧を削るべきと解説しています。括弧があると文が読みにくくなるのです。残念ながら、RedPen では「必要でない括弧」を識別できません。かわりに、RedPen の ParenthesizedSentence は括弧の用法に制限をかけます。かけられる制限は長さ、入れ子、一文に存在してよい数です。詳しくはマニュアルを参照してください。
「の」の多用
「文章の書き方」の 29ページ目では格助詞「の」の利用に注意するべきという記載があります。格助詞「の」は名詞を接続する便利な助詞ですが、使うと文が曖昧になります。そのため「の」のかわりに、情報量の多い単語で名詞を接続しましょう。RedPen は JapaneseAmbiguousNounConjunction を提供しています。JapaneseAmbiguousNounConjunction は 格助詞の「の」+名詞連続+格助詞の「の」という「の」の利用でも曖昧性が生じやすいパターンを検知します。
弱い表現
「かもしれない」などの弱い表現（ぼかした表現）は技術文書の持つ正確性を損なってしまいます。弱い表現の利用は十分注意してください。ぼかした表現については「数学文書作法」の 2.5章に記述されています。RedPen では WeakExpression という機能で弱い表現を検知します（英語のみ対応）。日本語についても早期に対応致します。
順接の「が」
「文章の書き方」の 27ページ目、に順接の接続助詞「が」についての記述があります。そのなかで「が」には、順接と逆接があり、順接の「が」は使用しないようにと述べています。
たとえば、以下の文は順接の「が」を使用しています。
今日は早朝から出発したが、無事会場に到着した。
残念ながら、使用されている「が」が順接か、逆接かは単純には判別できません。そこで RedPen の DoubledConjunctiveParticleGa (v1.7より対応)
は接続助詞「が」の多用のみを検査します。具体的には接続助詞の「が」が文中に二回以上利用されたときに、エラーを出力します。たとえば、DoubledConjunctiveParticleGa は以下の文に対してエラーを出力します。
今日は早朝から出発したが、定刻通りではなかったが、無事会場に到着した。
あきらかな誤り
以下の項目は指南書では指摘されていないですが、執筆者がやってしまう、あきらかな誤りです。
単語の連続使用
「私ははエンジニアです」のように助詞を連続して書いてしまう場合があります。RedPen は同一単語が連続で使用された箇所を検知する SuccesiveWord という機能を提供しています。
同一の節
私は「節の順番を換えた際に元あった場所の節を消し忘れた」という事例を知っています。これはケアレスミスと言えますが、同時に長い文書を書いているとどうしても起こってしまう問題です。RedPen の DuplicateSectionは類似する節（章）を発見するとエラーを出力します。
ギャップのある節
長い文書を書いていると節間の内包関係に注意がいかず、ミスがおこります。たとえば、以下のサンプルでは 1章の直下に節 1.1.1 が現れています。しかし本来であれば、節 1.1.1 と 1 章の間には節1.1が来なくてはなりません。
= 1章
...
=== 節 1.1.1
=== 節 1.1.2
...
RedPen の GappedSection は節の入れ子関係にギャップがあるとエラーを出力します。
同一内容の文が連続する
文書を書いていると同一の内容を持つ文を続けてしまう場合があります。同一の文が連続してしまうのは、いくつか理由があります。エディタのペーストコマンドを誤って実行してしまう場合や文をリファクタリングした結果ほぼ内容の文が連続してしまう場合もあります。そこで RedPen は SuccessiveSentence という機能（v1.7より対応）を提供します。この機能は類似した文が連続して現れるとエラーを出力して教えてくれます。
表記ゆれ
日本語の文書を書いていると、「引っ越し」と「引越し」のように単語の表記が揺れてしまいます。RedPen v1.10 から導入された JapaneseExpressionVariationは、表記ゆれの可能性がある単語ペアを抽出してくれます。詳しくい使い方は、RedPen v1.10 の新機能（表記ゆれ対応とエラーレベルの指定）を参照してください。
指南書での記述が発見できていない項目
以下、書籍や指南書での記述は発見できていないのですが、私が過去に注意された項目です。
空の節、章
学術雑誌用の論文を書いていた時のことです。論文のある節の直後で小節を開始したところ、査読者から注意を受けました。注意の内容は「学術雑誌用の論文はスペースが充分あるので、小節が開始するまえに節の要約を入れると読者が理解しやくなる」でした。RedPen が提供する EmptySection は空（小節が列挙されているだけ）の節を発見するとエラーを出力します。
長い漢字の連続
私は昔とある書籍を書いていて、編集者の方から「長い漢字の連続は読みにくい」とい指摘されました。連続する漢字は、単語の切れ目がわかりにくく読みづらくなります。LongKanjiChain は長過ぎる漢字連続が使用された箇所を教えてくれます。
実現できていない機能
以下、未だ RedPen でサポートできていない項目です。今後この記事とともに順次追加してゆく予定です。
- 「代名詞」の多用
- 「も」の多用
- 同一レベルの節が一つしかない
- 受動態の多用
- 疑問文
おわりに
著名な文書執筆に関する指南書で述べられている「文書の悪い点」を RedPen で検知する方法について解説しました。今後 RedPen のリリースとともに本文書の内容に修正が加わってゆく予定です。