(25日目-2) 僕の考えた Sphinx が目指すもの

このアドベントカレンダーは Sphinx & blockdiag アドベントカレンダーなので、
最終日のネタとしてもう一本、"僕が考えた Sphinx が目指すもの" としてまとめてみます。
ちなみに僕は Sphinx の開発者ではないので、あくまで "僕が考えた" なのでご注意ください。

誰のためのツールなのか

Sphinx はもともと Python のドキュメントを生成するために作られたツールであるため、
UNIX のテキスト文化に強く影響を受けています。
そのため、Sphinx と相性がいいのは普段からテキストを書きなれている人たちです。
こうした人達はエディタの設定や、バージョン管理、ツール選定など、
テキストであるメリットを最大限に得ることができます。

反対にテキストによるマークアップに慣れていない人たちには、
慣れない環境で文章を書くことになる上に、メリットが理解できないという苦労がまっています。
なお、図や装飾が少ない文章が中心のドキュメントであれば、
最低限のマークアップとちょっとした書き方のコツ(インデントやテキスト幅の把握)を
覚えてもらうことで一緒に書き進めていけるようになるかもしれません。

今の Sphinx のネックになるもののひとつに図があります。
統合型の Office スイートであれば GUI 操作でちょっとした絵は簡単に作れますが、
Sphinx では他のツールで絵を作って、それを貼り付ける必要があります。
blockdiag などのテキストベースの図作成ツールも出てきていますが、
これらも万能ではないため、まだ手をかけなければならない箇所です。

こうしてまとめてみると、今の時点では Sphinx は万人向けでも汎用的でもありません。
例えば「絵がメインの提案資料」や「非技術者にも書いてもらうドキュメント」など、
Sphinx が向いていないケースは多々あります。

今のところ Sphinx は技術者向けのツールとして、価値があるのではないでしょうか。
もし Sphinx でドキュメントを書き始めようとする際は、

関わるメンバーに Sphinx が向いているか (慣れてもらえるか)
内容は Sphinx に向いているか

という点を考える必要がありそうです。

Sphinx のライバルたち

僕がイメージする Sphinx のライバルとなるツールは MS-Word です。
Excel でドキュメントを書く風習がある地域があるそうですが、
もし図表が少ないのであればこれらもライバルになると思います。
もし図表が多い Excel ドキュメントであれば少しターゲット層が違うのではないかと思われます。

一部で Docygen や Javadoc と比較していることがありますが、
こういったソースから抽出する API リファレンスとしては
Sphinx の autodoc などはまだまだ改善の余地があるため、置き換えるのは難しいでしょう。*1

もうひとつ比較するツールを上げるとすれば Wiki になります。
Sphinx と同様にテキストベースでマークアップをし、見やすい形式で表示するという部分で共通点がありますね。
また、すでに多くの人が Wiki でドキュメントを書いて慣れており、
また書き挙がっているドキュメントが存在するというのは強みです。

もしあなたが新しくドキュメントを書き始める際は
これらを比較することも重要かもしれません。

Sphinx が教えてくれたこと

では Sphinx のよいところとはどこなのでしょうか?

今までたくさんの Sphinx 使いに会ってきて、また、ついこの間 Sphinx ハンズオンを開催して、
いろんな人から話を聞いた結果、僕が導き出した Sphinx の良さは次のみっつです。

かんたん
- reST のマークアップは覚えやすい
たのしい
- 書いたテキストがきれいな形に変換されるのがたのしい
つづけられる
- 更新しやすい

そしてこのみっつはすごく密接に繋がっています。
「かんたん」は「たのしい」に繋がって、「たのしい」は「つづけられる」に繋がって、
最終的にこの三つのキーワードから「うれしい」につながっていきます。

ちなみに、この三つのキーワードを反転するとこうなります。

たいへん
つまらない
つづかない

僕が Sphinx に出会う前にドキュメントに対して抱いていたイメージそのものです。
いままで、ずっとドキュメントは面倒で辛いものとして扱っていて、
いつもドキュメントの作業は後回しにされ続けていました。

もしドキュメンテーションに対して嫌なイメージを持っている人は Sphinx を触ってみてください。
この「たのしさ」は使ってみないと体感できないので、ドキュメントに対するイメージを変えるために一度触ってみるべきです。

Sphinx に足りないもの

Sphinx で文書を書くのはたのしいのですが、まだまだ磨かなくてはならない部分は多々あります。
ぱっと思いつくところを挙げていきます。

編集ツール

Sphinx は reST で本文を書いてmake コマンドを実行する、という操作を繰り返してドキュメントを書きます。
omake を使ってみたりエディタを設定することで軽減することもできるのですが、
やはり編集内容をプレビューしながら文書を編集できるリッチなエディタが必要でしょう。
耳にした範囲では Web 上で編集できるエディタをつくっているという話がありました。

画像ツール

上でも触れましたが、Sphinx の弱いところに図を埋め込むというのがあります。
blockdiag や PlantUML、ditaa などの Sphinx と親和性の高いツールもそうですし、
編集ツールで連携できる(Web 上でおえかきして埋め込むなど)という方法も出てきそうです。

この部分はもっともっと進化が求められる部分でしょう。

PDF まわり

Sphinx の触れ込みのひとつに、何種類ものフォーマットで出力できる、というものがあります。
多くの人が興味をもつのが HTML と PDF 出力です。
HTML 出力は特に苦労することなく標準の機能でかんたんに扱えるのですが、
PDF 出力に関しては Sphinx 本体にパッチをあてなくてはならなかったり、
最新の TeX をダウンロードしたりする必要があるため、多くの人がつまずいてしまうポイントになっています。

この部分はパッチを取り込んでもらうのと、各ディストリビューションに頑張ってもらうしかないのですが、
Sphinx が使いやすくなるためには必須の項目でしょう。

ドキュメントテンプレート

いろんな方と話していると、ドキュメントに何を書くべきなのか、というものが結構あやふやな状態のようです。
かくいう自分も何を書くのか、何を書かないのか、という取捨選択がちゃんと出来ているか自信がありません。
せっかく Sphinx を使ってドキュメント更新がしやすくなっているのですから、
ドキュメントに書くべき項目もシェイプアップして lightweight にしたいですよね。

来年には 2012年に書かれるべきドキュメントはこんなものなんてまとめが出てるといいですね。