エンジニアが成果物を作るたびに、成果物を解説する技術文書が必要になります。文書執筆を専門とするテクニカルライタが必要な技術文書を書いてくれる場合もありますが、多くはエンジニア自身が作らなくてはなりません。

成果物を利用するユーザは技術文書を読みながら、制作物を理解します。そのため技術文書が読みにくかったり、必要な記述が抜けているとユーザは制作物を利用できません。結果的にドキュメントがわかりやすく記述されていないために、制作物を作成したエンジニア自身が対応に追われて、新しい制作物を作る時間がとれなくなってしまいます。そのため、現在ではわかりやすい技術文書を作成する技術はエンジニアに必要なスキルになっています。

技術文書を作成する難しさ

しかし残念ながらわかりやすい技術文書を作成するのは骨の折れる作業です。とくに技術文書を複数人数で書いていると専門用語や句読点が揃っていなという単純な問題がおこります。その結果、内容を十分にチェックをする時間が取れません。

技術文書を自動検査するRedPenというツール

RedPenというツールは執筆者が従うルール（規約）を自動で検査するツールです。

RedPenの特徴

RedPenは以下の特徴を持ちます。

マークアップ言語の対応

技術文書はテキスト以外にも多くの要素からなります。そのため多くの技術文書はマークアップ言語で記述されます。

RedPenは技術文書で利用されるマークアップ言語（Markdown、LaTeXなど）をサポートしているため、ユーザは記述中の文書をそのまま検査できます。

設定が柔軟

執筆者はそれぞれ異なる規約に基づいて文書を記述します。そのためRedPenは規約を表現するための設定が柔軟に変更できるように設計されています。規約を表す設定はRedPenの設定ファイルとして保存して利用します。文書をGitなどのバージョン管理システムで管理する場合には、規約をリポジトリに同梱します。リポジトリにRedPenの設定ファイルを同梱することで、執筆グループのメンバ全員が同じ規約に基づいて執筆できます。

多言語に対応

最近は日本発のオープンソースプロジェクトでも利用方法は英語で書く習慣が広がっています。RedPenは言語を問わず利用できます。

拡張できる

RedPenに欲しい機能が足りないと思った場合には、RedPenの機能を拡張できます。拡張に利用できるプログラミング言語はJavaとJavaScriptです。特にJavaScriptで拡張を作成する場合には、関数を一つ実装するだけで実装できます。

エディタに対応

RedPenはコマンドラインツールとして利用できますが、それ以外にもサーバの機能（REST API）を提供しています。

さらに、一部のエディタにはプラグインが提供されています（プラグインの多くはRedPenを利用するエンジニアがオープンソースプロジェクトとして公開しています⁠）⁠。RedPenプラグインが提供されているエディタを使用すると、文書を書きながら検査を並行して実行できます。現在RedPenのプラグインが利用できるエディタにはAtom、Emacs、Vimなどがあります。詳しくはRedPenのホームページを参照してください。

まとめ

本稿では文書検査ツールRedPenについて解説しました。是非、文書の執筆で利用してみてください。