November 19, 2017

RedPenで文書校正する

文書検査ツール RedPenを導入してみました。

背景

現在仕事のプロジェクトをアーキテクトとして担当しているのですが、 要件定義で生産的な活動をしてくれるメンバがおらず、ほぼ一人で要件定義書を 書き上げることになりました。

他人のチェックが通っておらず、ちょっとしたミスも多いので校正ツールを導入する ことにしました。

最初はJustSystemのJustRightなどを考えたのですが、以下の理由によりオープンソース の RedPen で文書の検査をすることにしました。

  • JustRightを購入する費用が捻出できない。
  • そもそも 要件定義書は Sphinxで記述し て、RedPenはreStructuredTextをサポートしている。

RedPen 使用感

かなり文書を書き上げてから使用したので、最初はものすごい量のエラーに圧倒されました。

しかし、指摘をチェックして気づいたことも結構あり大変ためになりました。

まず、指摘が多かったのは以下のものです。

  • KatakanaEndHypeh
  • JapaneseAmbiguousNounConjunction
  • ParenthesizedSentence

KatakanaEndHypeh

これは、カタカナの語尾がハイフンで終わるケースですね。

「コンピューター」や「アーキテクチャー」などが古いJISZ8301などの規約だと、 ハイフンで終わらせず「コンピュータ」や「アーキテクチャ」なのだそうです。

RedPenではこれにならって、以下のルールになっているようです。

  1. 単語が三文字もしくはそれ以上の場合には、ハイフンで単語は終わらない。
  2. 単語が二文字もしくはそれ以下の場合には、単語はハイフンで終わってもよい。
  3. 単語が複合語の場合には各々の部分単語について条件が適用される。
  4. 以上のルールにおいて、拗音をのぞきハイフンは一文字としてカウントされる。

これは私の感覚と違っているのですが、私自身も表現が揺れてるところがあった ので、今回はRedPenに従いました。

平成3年6月28日 内閣告示第二号『外来語の表記』から事情が変わっていて、 本来は「コンピューター」「アーキテクチャー」の方が正しい気がします。

JapaneseAmbiguousNounConjunction

私の場合、これが一番たくさんひっかったエラーでした。

「他のコンポーネントのエラーを」などのように格助詞「の」で文章を繋いだものです。

自分では気づいなかったのですが、この表現を予想以上に使っていました。そして確かに 言われてみれば文章の意味が曖昧になっているケースに気づきました。

例えば「他のコンポーネントのエラーを」というのは、「他のコンポーネント」のエラー なのか「他の」コンポーネントのエラーのなのかわかりませんね。

これを格助詞を並べずに言い換える表現を考えると、意外にも文章の意味がはっきりし てくることに気づいたのです。

JapaneseJoyoKanji

これは括弧に関する規約で、一文で使用される括弧の頻度や括弧のネストなどをみて くれるのです。

実際には括弧がおかしいというよりは、箇条書きの句読点が抜けていたり、どこかで 文の区切りがおかしかったりということが原因でした。

このような文はSphinx上もエラーを抱えているケースが多かったので、その事前の チェックとしても有効でした。

導入に当たっては

私はかなり文書が書き上げた状態で導入したので、ものすごい量のエラーを除去で 疲弊してしまいました。

反省としては、2点あります。

  1. プログラムのテストツールと同様テストファーストです。CIで組み込んで書き始め からチェックして言った方がおそらく生産性が高く、除去の工数も小さくすみます。
  2. 先のKatakanaEndHypenのように実情と合わないルールもあると思います。その場合は、 サクッと外しちゃいましょう。

なお、設定はファイルは導入フォルダ1に設定ファイルがあるので、プロジェクトの フォルダにコピーしてきて、不要なルールを消していきましょう。


関連リンク


  1. macOSの場合は、/usr/loca/Cellar/redpen/1.9.0/libexec/conf にxmlの設定ファイル があります。

    [return]

© 沙門