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

第1回 自動文書検査ツールRedPenとは?

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

はじめに

本連載ではRedPenという自動文書検査ツールの紹介とRedPenを利用した技術文書の校正方法について説明します。RedPenはオープンソースプロジェクトで,現在もゆっくりと開発が続いています。RedPenのホームページは次のとおりです。

RedPenは技術文書をターゲットにした文書の自動検査ツールです。技術文書にはマニュアルやチュートリアル,論文,仕様書等が含まれます。この記事のようなソフトウェアツールの紹介文書はもちろん技術文書の一つといえます。第1回の今回は,はじめに技術文書の特徴を解説し,その後RedPenを開発した動機について紹介します。記事の後半では,RedPenの特徴と利用方法について解説します。

技術文書の特徴

RedPenが対象とする技術文書ですが,作文や日記,文学作品等とは大きく異なる特徴をもちます。

最大の違いは,技術文書にはわかりやすさが求められる点です。詩や歌謡曲の歌詞にはわかりやすさを放棄し,わざと曖昧な部分を残すことでより心に響く作品となる場合があります。しかしわかりやすさが第一に求められる技術文書には余韻や深みは必要ありません。

技術文書に求められるわかりやすさとは単純には内容が理解しやすいことを意味します。拡大解釈すると,対象となるすべての読者が同一の意図を読み取れるといえるかもしれません。

日記等と違って技術文書は自分以外の第三者が読むため,恥ずかしくない文書を書く必要があります。恥ずかしい文書は利用する特殊文字や専門用語が揃っていなかったり,"彼がが行く" のように明らかな文法間違いが多数存在します。また"すごい"や"っていうか"などの口語が混じってしまっていると,文書のみならず,文書が扱う製品の品質までにあらぬ疑いをもたれてしまいます。

RedPenを開発した動機

ソフトウェアエンジニアはプログラムだけではなく,たくさんの技術文書を書いていると思います。私の場合,プログラムとほぼ分量の文書(チュートリアルやマニュアルなど)を書いてきました。ただプログラムを書いている時ほど安心して文書を書けないという悩みをもっていました。

ソフトウェアツールを開発する際には多くのテストを書きます。またCheckStyleやlintなどの静的解析ツールを利用してフォーマットのエラーを自動で検知する環境を整えます。テストを整備したり静的解析ツールを導入することで,プログラムを変更する際に新たな問題(バグ)が発生しないという安心感を得られます。

一方私が文書を書いている時には安心感はありません。技術文書の執筆環境にはテストもありませんし,静的解析ツールも存在しないためです。ちょっとした変更でも,誤りをやフォーマットミスを引き起こしたのではないかと常に不安な気持ちで作業することになります。結果文書を変更をするのが億劫になってしまい,なかなか文書の質が向上しませんでした。

このような状況に対して,RedPenは一部の静的解析ツール(CheckStyleやlint)に相当する機能を文書の執筆環境に提供します。私はこのツールを,文書作成でも最低限の検査を自動で行いたいという動機で開発しています。

以下,RedPenの特徴を紹介し実際に使ってみます。

RedPenの特徴

前項で述べたようにRedPenはプログラムの静的解析ツールに相当する機能を技術文書に対して提供します。具体的には文長のチェックや不正な表現を検知などわかりやすさに寄与する機能と,登録された以外の記号が出現した時にエラーを出力するようにフォーマットの不統一を検出する機能が提供されます。主なRedPenの特徴は次のとおりです。

言語非依存

RedPenはどの自然言語(英語や日本語,中国語など)で記述された文書にも適用できます(注:一部機能は特定の言語でしか動作しないものがあります)。本連載の第4回では英語の文書にRedPenを適用してみます。

柔軟な設定

RedPenが対象とする技術文書の規約は所属組織によって大きく異なります。RedPenは組織の規約に対応できるように設定が柔軟に行える仕様となっています。

コマンド実行

RedPenは単一コマンドで実行できます。そのため,他のシステムの中に組み入れることが比較的容易です。第2回ではCI環境でRedPenを使用して自動チェックを実現します。

RedPenを使ってみる

ではRedPenを使用してみましょう。RedPenはUnix系のOSとWindowsで動作します。今回はUnix系のOS(Mac)を利用します。

必要なソフトウェア

RedPenは次のソフトウェアを必要とします。

  • Java(バージョン 8)

ダウンロードと解凍

RedPenをダウンロードします。RedPenのリリースページからダウンロードできます。

ダウンロードされたファイルを次のコマンドで解凍します。

$tar xvf redpen-cli-1.0-assembled.tar.gz
x redpen-cli-1.0/lib/redpen-core-1.0.jar
x redpen-cli-1.0/lib/kuromoji-0.7.7.jar
x redpen-cli-1.0/lib/commons-io-2.2.jar
...

結果,redpen-cli-1.0というディレクトリが生成されます。

インストール

RedPenをインストールします。インストールと言ってもRedPenのソースファイルをコピーするだけです。たとえばRedPenを/usr/localにインストールするには次のコマンドを実行します。

$cp -r redpen-cli-1.0 /usr/local/redpen

続いてRedPenのインストールディレクトリを環境変数PATHに追加します。次のようにredpen/binを.bashrcに追加してください。

export PATH=$PATH:/usr/local/redpen/bin

他のシェルを利用している場合も同様にPATHにredpenディレクトリを追加してください。以上でインストールは完了しました。

著者プロフィール

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

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