■■■怠惰なプログラマのためのドキュメント作成実践
■■はじめに
ソフトウェア開発においてドキュメントは欠くことのできない重要なものです。ドキュメントと聞くと、キングファイルに綴じられた分厚い紙束を連想してうんざりする方も多いかと思います（筆者もそうです）。一口にドキュメントと言っても多種多様ですが、その本質は書き手と読み手のコミュニケーションの手段です。したがって、読む気の起きないドキュメントや誰も読まないドキュメントは本来の目的を達していないことになります。
■ドキュメントのあり方の変遷
ドキュメントのあり方は、技術の進歩や文化の変遷によって変わり続けています。身近な例として、携帯電話のマニュアルがあります。
筆者が携帯電話を使い始めたのは十数年前になりますが、機能やサービスの増加に伴ってマニュアルは年々分厚くなってきました。もちろん必要性があってのことですが、読む気が失せるのも正直なところです。ところが、最近は事情が変わってきました。携帯電話に同梱されているマニュアルは必要最低限の内容に絞った薄いものとなり、詳細なマニュアルはWebで公開される形が一般的になってきています。これなら、初めて使うユーザにも隅々まで使い倒したいパワーユーザにも適した形であると言えそうです。
ソフトウェア開発に関わる様々なドキュメントもまた、同様に時代に適応していかなければなりません。
■ところでこの記事、何の連載だっけ？
そろそろ連載の趣旨に戻らないと怒られそうなので、このへんでEmacsのことを思い出すことにします。ドキュメントと言うと、Emacsに閉じた世界ではinfoで事足りるという向きもありますが、全人類がEmacsを使っているわけではありません。今回は、Emacs上で動作するアウトラインエディタであるorg-modeを使って、効率的なドキュメントの作成と維持管理についてアリエルでの実例を基にお話しします。主にソフトウェア開発者間でのコミュニケーションを目的としたドキュメントについて取り上げますが、考え方は幅広く応用できると思います。
■■ドキュメント、何で書いてますか?
ドキュメント作成の方法はプロジェクトの事情に応じて様々だと思います。ここでいくつか簡単に触れておきます。
■WordとExcel
世間一般ではソフトウェア開発におけるドキュメントというと、やはりWordやExcelで作成しているプロジェクトが大多数ではないかと思います。個人的に、Wordで複雑な表組みができる人は尊敬はしますが自分がそうなりたいとは全くもって思いません。Excelは筆者の記憶が確かならば表計算ソフトウェアだったはずなのですが、最近は方眼紙として使われることが多いようです。画面上ではセルに収まっているテキストが印刷すると収まらない問題が解消される気配すらないので、Excelを積極的に使う気にはなりません。また、WordにせよExcelにせよ、grepで検索できないという致命的欠陥を抱えています。アリエルのグループウェアなら全文検索できるよ！という宣伝はさておいて、そんなわけでソフトウェア開発の現場からのWordやExcelの絶滅を願って止まない今日この頃です。
■HTMLとwiki
一方で、HTMLで構成されたドキュメントは、読み手の立場からすると非常に便利です。ブラウザさえあれば環境を選びませんし、よく参照するページをブックマークしておけるのも便利です。Webサーバに置いておけば個人に配布する必要もありません。しかし、実際にHTMLでドキュメントを書くのはなかなか大変な作業です。Webオーサリングソフトウェアを使うにせよ手でタグ打ちするにせよ、ドキュメントの内容とは本来関係のないレイアウトやデザインの部分に注意を払わなければなりません。この問題に対する一つの解はwikiです。アリエルではBTSとしてtracを使っているので、筆者の所属部署ではプロジェクトに関わる情報を、tracのwikiを使って文書化して共有するのが一般的になりつつあります。誰でも編集でき、簡単な構文を覚えてしまえばドキュメントの内容に集中して書くことができます。プロジェクト内での情報共有の手段としては、wikiは非常に優れたツールだと思います。
■ところでこの記事、何の連載だっけ？
さて、気付くとまた脱線していました。ちゃんとEmacsの話をしないと、今後執筆依頼が来なくなっては困ります（原稿料的な意味で）。幸いにも、アリエルにはEmacsを活用して効率的なドキュメント作成に取り組んでいる実例があります。主力商品であるAriel AriOne Enterpriseはグループウェアとしての側面の他に、アプリケーション開発環境としての側面を持っています。ユーザ企業の開発者がアプリケーションを開発できるようにするため、ドキュメントやライブラリを整備してSDKとして提供しています。このSDKドキュメントの作成に、Emacsのorg-modeが活用されています。
■■org-modeの基本
はじめに、org-modeのご紹介です。org-modeはEmacs上で動作するアウトラインエディタであり、タスク管理ツールであり、スケジューラであり、組版システムであり、それら以外の何かだったりします。Emacsに標準で含まれているので、何もインストールすることなく使い始めることができます。あまりに多機能なので、今回はアウトラインエディタとしての機能に絞ってご紹介します。完全な解説は以下の公式サイトをご参照ください。
http://orgmode.org/
■org-modeを使う
org-modeに切り替えるには、”M-x org-mode”とタイプします。拡張子が.orgのファイルを自動的にorg-modeで開くようにするには、.emacsにリスト1のように記述します。
■見出し
アウトラインエディタの基本は文書の構造化です。org-modeでは、行頭にアスタリスクをつけると見出しになります。見出しを階層化することで、文書の構造を表現します。文書構造はツリー状になり、見出しにカーソルを置いた状態でTabキーを押下するとツリーを展開したり畳んだりすることができます（
）。
■リスト
見出しと同じくらいよく使われるのがリストです。org-modeでは、番号付きのリストと番号なしのリストを作成できます。番号付きリストは、”1.”または”1)”のように書きます。番号なしのリストは”-“または”+”で始めます。リストには階層を持たせることができます（
）。
”M-<RET>”とタイプすると、カーソルのある行と同じレベルの項目を追加できます。”M-s-<up>”と”M-s-<down>”で項目を上下に移動できます。この時、番号付きリストでは自動的に番号を振り直してくれるので便利です。また、階層を持ったリストの場合は下位項目ごと移動できます。
■リンク
ファイル内やファイル間でリンクを張ることができます。リンク上で”C-c C-o”とタイプするかマウスでクリックすると、リンク先にジャンプします。基本的な構文はリスト2のような形式です。リンクを作成すると、
のように下線付きで表示されます。
内部リンクの場合、リンク先には文字列を指定します。ファイル内でその文字列が最初に現れたところへのリンクになります。外部リンクの場合は、リンク先にプレフィックスを付けることで様々なターゲットにリンクすることができます。主なものをリスト3に挙げます。
■例示
コード例などを記述する場合、行頭にコロンを付けます（
）。Emacs上では意味付け程度ですが、後ほどHTMLに変換する際に<pre>タグに変換されるので、インデントが意味を持つ箇所はコロン付きで記述する必要があります。
■■org-modeでドキュメントを書く
■org-mode事始め
アリエルに入社してからEmacsを使い始めた筆者ですが、初仕事は開発環境の構築手順書を作ることでした。冒頭でも触れたようにWordやExcelにはうんざりしていたので、プレーンテキストでありながら書きやすく読みやすい書式を模索していてorg-modeに辿り着きました。
手順書のターゲットは社内だったので、凝ったことはせず前節で紹介した程度の書式を使って書いただけですが、おそらく世間一般よりEmacsユーザの比率が高いアリエルでは有用だったようです。もちろん、社員全員がEmacsを使っているわけではありません。しかし、org-modeの書式は特異なものではなく、他のエディタで読んでも自然に理解できます。また、後述するように他のフォーマットに容易に変換できるので、たとえ周囲にEmacsユーザがいなくても、org-modeでドキュメントを書くメリットは十分にあると思います。
■org-publishでお手軽HTMLドキュメント
Ariel AirOne Enterprise上で動作するアプリケーションをお客様が開発する初の案件で、筆者がリーダーを務めることになりました。社内で開発する際には製品本体のソースコードを読み漁りながら開発を行っていましたが、お客様が作るとなるとそうはいきません。そこで、社外向けのドキュメントを整備する必要が生じました。ここで使用した手法が、org-modeで書いたドキュメントをorg-publishでHTML化して提供する、というものでした。
org-publishは、org-modeで記述したファイル群をHTML化し、Webサーバにデプロイする機能です。アウトラインに基づいたタグ付けが行なわれ、ファイル間のリンクもそのまま維持されます。多数のファイルから構成されるWebサイトをコマンド1つで生成できるので、メンテナンス性の面で非常に優れたWebサイト構築システムと言えます。
org-publishを使用するには.emacsにリスト4の記述が必要です。
org-publishによるWebサイト生成には、プロジェクトの定義が必要となります。プロジェクトの定義は.emacsに記述します。筆者が実際に使用していたプロジェクトの定義をリスト5に示します。
リスト5で定義している各プロパティの意味を表1に示します。publishing-functionでorg-publish-org-to-htmlを指定していることに注目してください。org-publish-org-to-htmlは、org-modeで書かれたファイルをHTMLに変換する関数です。publishing-functionで指定する関数次第で、HTML以外の形式にも変換が可能なのです。変換を行わずファイルコピーだけを行うorg-publish-attachmenや、LaTeXに変換するorg-publish-org-to-latexなどが用意されていますし、必要であれば自分で書くこともできます。
org-publishには、ここで取り上げた以外にも多数のプロパティがあり、動作を細かく制御することができます。以下のサイトに詳細な説明がありますのでご参照ください。
http://orgmode.org/manual/Publishing.html
プロジェクトの定義ができたら、あとはコマンド1つですべての処理が行われます。”C-c C-e e”とタイプすると、プロジェクトを指定して処理を実行できます。”C-c C-e p”とタイプすると、現在のバッファで開かれているファイルを含むプロジェクトに対して処理が実行されます。また、”C-x C-e f”で現在のファイルのみを処理できるので、大量のファイルからなるプロジェクトにちょっとした修正を加える場合も効率良く作業できます。
■Emacsとext-docの合わせ技
さて、このへんから意図的に脱線を始めます。さきほどの事例はEmacsだけで完結していましたが、その後公式なSDKとしてドキュメントを提供することとなったため、より読みやすくメンテナンスの負担も軽い方法の再検討を行いました。その結果、ext-docというツールと組み合わせることとなりました。
ext-docはJavaScript用のコメントプロセッサです。ExtJSのドキュメンテーションに使用されているので、ご覧になったことのある方も多いのではないでしょうか。見栄えが良く使いやすいドキュメントが簡単に生成できます。以下のサイトから入手できます。
http://code.google.com/p/ext-doc/
SDKは大きくライブラリのAPIリファレンス部分とチュートリアル部分から構成され、ライブラリはJavaScriptで記述されています。ソースコードとは別にAPIリファレンスを書くのは1事実1箇所の原則に反しますし、往々にしてメンテナンスを忘れがちになるので、ドキュメンテーションコメントとしてソースコードに記述した情報からドキュメントを生成する方法を選択しました。厳密に考えるならばドキュメンテーションコメントも冗長ということになるのですが、まあそこまで気にしていると人生やってられません。
一方で、チュートリアル部分についてはドキュメンテーションコメントからの生成という方法はそぐいません。しかし、リファレンスとチュートリアルは相互参照するものなので、ドキュメントを分けてしまうと使いにくくなります。このため、チュートリアル部分は引き続きorg-modeで記述してHTMLに変換し、それをext-docで生成されたドキュメント内に組み込む形としました。
ドキュメントの生成プロセスは3段階から成ります。まず、org-modeで記述されたファイルをHTMLに変換します。次に、変換結果のHTMLをext-docが処理できる形に変換します。最後に、ext-docでドキュメントを生成して完成です。
org-modeからHTMLに変換する部分は、org-publishではなくEmacsのバッチモードを使用しています。これは、シェルスクリプトでドキュメント生成の全プロセスを一括実行できるようにするためです。この変換処理を行っている部分のシェルスクリプトを抜粋したものをリスト6に示します。
続いてext-docでの処理用にHTMLを加工する部分です。ここは、rubyで書かれたスクリプトを使っています。やっていることはシンプルで、”/** @class ドキュメントタイトル”と”*/”の間にHTML全体を挟むだけです。これで、ext-docはHTMLを大きなドキュメントコメントとして認識します。ここまでできてしまえば、後はext-docに任せてしまえばドキュメントのできあがりです。完成したドキュメントは
のようになります。
■■おわりに
ソフトウェア開発において、ドキュメントを書くという作業は忌み嫌われる傾向にあります。とくにプログラマというのは怠惰な生き物なので尚更です。今回ご紹介した事例は、楽をするためにはどんな苦労も厭わないプログラマの習性が結実したものと言えます。ドキュメントの作成や維持管理にお悩みの皆様、これを参考にドキュメントの生成システムを構築してみてはいかがでしょうか。それなりの初期投資は必要ですが、十分に回収できること請け合いです。
最近のコメント