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

第2回 RedPenを利用した文書の継続的検査への取り組み

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

今回はRedPenを利用して文書を継続的に検査する方法について解説します。文書の継続的検査環境では,執筆中の文書をGitなどのバージョン管理システムで管理します。著者が行った変更が,サーバにあるバージョン管理システムにプッシュされるたびに自動でRedPenが適用されます。

本稿では,はじめにGitなどのバージョン管理システムで文書を管理するメリットについて述べます。その後継続的インテグレーションの説明を行い,RedPenと組み合わせて文書の管理に利用してみます。

文書をGitで管理

最近は文書の管理にGitなどのバージョン管理システムを利用する人が多いのではないかと思います。私もある程度の大きさの文書はすべてGitで管理しています。昔の状態に簡単に戻れるという以外にも,文書管理にバージョン管理システムを利用すると次のようなメリットを享受できます。

マージ処理

バージョン管理システムを利用することで,共同執筆者から送られてくる変更要求をマージする作業がシンプルに行えます。さらに執筆メンバーがプルリクエストを送る形で執筆すると,各変更のレビューを行った上でマージするという流れが徹底できます。レビューが徹底されることで,文書の変更に関する知見がグループメンバに自然に共有されます。

バージョン群の管理

バージョンごとに少しづつ異なるマニュアルや仕様書には,バージョン管理システムが提供するタグやブランチが利用できます。さらにマニュアルに新しく間違いが見つかった場合でも,過去の各バージョンにも同様に存在する該当箇所を修正する(マージ)させる処理も簡単に行えます。

継続的インテグレーション

継続的インテグレーションはソフトウェア開発で近年利用されている手法の一つです。Wikipediaでは継続的インテグレーション(CI)について次のように説明されています(2014年11月時点)⁠

継続的インテグレーション,CI(英: continuous integration)とは,主にプログラマーのアプリケーション作成時の品質改善や納期の短縮のための習慣のことである。エクストリーム・プログラミング(XP)のプラクティスの一つで,狭義にはビルドやテスト,インスペクションなどを継続的に実行していくことを意味する。特に,1990年代後半以降の開発においては,継続的インテグレーションをサポートするソフトウェアを使用する傾向が強まってきた。

継続的インテグレーションを実践するツールが多数提案されています。特に有名なCIサーバとしてJenkinsがあります。CIサーバを導入することで,プッシュごとのテストを自動化し,バグや不具合が混入した場合にいち早く発見できます。バグや不具合は混入して時間がたつほど修正するコストが増大します。バグの早期発見により開発コストが低減できることが知られています。

継続的インテグレーションと文書執筆

ハードの製品のように一度作って終わりという代物ではなく,ソフトウェアは日々改善,修正を行い徐々に形を変えていきます。日々少しづつ変わることで,簡単に不具合やバグが混入します。そこで継続的インテグレーションが提供する不具合の早期発見が力を発揮してくれます。

日々形が変わり簡単に不具合が混入するという性質は文書の執筆でも同じだと感じています。ベンダが販売している製品のマニュアルは製品が利用されるあいだ,ずっと利用されます。さらに,製品のバージョンごとに少しづつ修正が加えられ続けます。もともとなかった機能が追加さたり,一部機能は提供を中止されるごとに製品のマニュアルは変更を強いられるのです。

ソフトウェアと同様に修正が加えられつづける文書が一定の品質を担保するには,先に述べたようにソフトウェアを管理する一部のツールが役に立ちます。Gitなどのバージョン管理システムはまさに好例ですが,私は継続的インテグレーションも文書の品質管理に寄与するのではいかと感じています。

コラム:研究論文の思い出

研究の論文なども長く苦しい推敲が必要です。たとえば私がデータマイニングの研究をしているとき執筆した論文は,最初の国際会議に受理されるまでに約3年かかりました。最終的に完成した論文は,はじめに書いた論文とは扱っているトピックは同一です。しかし語彙や段落構成,実験,論理展開など,ほとんどすべての部分が何度も書き直されています。恐ろしいことに,書き直されているあいだに何度もミス(語彙の変更が一部反映されていない,単純な文法ミスなど)が混入されてしまうのです。

論文は受理されるまでのあいだ,不受理された理由(コメント)に対するディフェンスを行いつづけます。関連論文との違いがわからないというコメントであれば,反論を追加するだけですのでそれほど大変ではありません。内容を読み違ったレビューア(査読者)がいる場合には,大手術が必要です。読み手が内容を読み間違わないように論理の展開を大きく構成し直す必要があります。一つずつ小さな改善を積み重ねることで,きちんとした会議や論文誌に通る可能性が上がります。

本連載の第4回ではLaTeXで書かれた文書に対してRedPenを適用してみます。

ちなみに私が先日テキストマイニングシンポジウムで書いた論文はRedPenを使って検査しながら作成しました。後日とある方から論文のフォーマットエラーをご指摘していただき恥ずかしい思いをしましたが,同時に指摘していただいた箇所にはRedPenに取り込めそうな機能が含まれていました。論文もプログラムも指摘(レビュー)していただくのはとてもありがたいですね :-)

継続的インテグレーションサービス

CIサーバの導入により多くの利益が得られることが知られていましたが,残念ながらCIサーバは通常インストールしたうえで運用する必要があります。そのため個人や小規模な組織では,運用コストがかかってしまい導入を見送る,もしくはせっかく導入してもうまく稼働していない場合がありました。

しかし近年,TravisWercker等のCI機能を提供するサービスが誕生したことにより,だれでも簡単に継続的インテグレーション環境が利用できるようになりました。ちなみに本稿ではCIサービスの一つ,Travisを利用して継続的な文書検査環境を作ってみます。

上述のCIサービスはGitHub上に存在するプロジェクトにCI機能を提供します。GitHubはGitシステムを利用したソフトウェアの開発,公開をサポートするサービスです。紙面の都合上GitHubの利用方法については本稿では解説しません。Web上にGitHubに関する多数のブログ記事が存在しますのでそれらを参照してください。

Travis

TravisはGitHubで管理されているプロジェクトに対して継続的インテグレーション環境を提供します。Travisを利用する際には,GitHubで管理されているプロジェクトのルートディレクトリに.travis.ymlという設定ファイルを保存します。

RedPenプロジェクトでもTravisを利用してテストの自動実行を行っています。以下ちょっと前のバージョンですが,RedPenで利用されていた.travis.ymlとなります。

language: java
jdk:
    - openjdk7

.travis.ymlにはいくつか設定項目がありますが,小規模のプロジェクトであればプロジェクトで使用している言語を指定するだけで最低限のテストを行ってくれます。上記の例ではlanguagejdkブロックでそれぞれ記述言語(Java)とJVMのバージョンを指定しています。

著者プロフィール

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

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

コメント

コメントの記入