他のツールとの比較

ドキュメントを書くツールにはさまざまなものがあります。以下のようなもののうち、何を使用しているでしょうか?

  • Word(OpenOffice, 一太郎)
  • PowerPoint
  • Excel
  • HTML直書き
  • Wiki
  • Sphinx
  • TeX
  • その他

ここでは、このなかの、Word/Excel/Wiki/Sphinxの4つを選び、メタファーを交えながら比較して、なぜSphinxが成長するドキュメントに適しているのか、他の物が適さないのかという説明をしていきます。ただし、Sphinxの良い所ばかりを取り上げて、他の選択肢を貶めるようなことはしないように心がけます。

Word

まずはWordです。Wordはドキュメント専用ツールです。Wordの優れている点は次の通りです。

  • 縦書きに対応。知り合いの小説家の人はWordを使っていました。
  • 日本語の文法チェックをしてくれます。商業レベルの文章を書くときに利用したり。
  • 単語単位の差分機能。編集の人と、変更箇所や指摘をやりとりする際に便利でした。
  • 論文、小説など、大きく構造を並び替えたりせず、文章の位置関係が比較的早期に決まるような長文の文章には適しています。
  • 参考文献とか索引も作れます。あとは差し込み印刷などもできます。

欠点としては、シーケンシャルな流れを直接扱うことは得意ですが、その分大きい文章の並び替えとかは大変です。1ファイルで構成されているため、複数人でいじるのも大変です。

Excel

Excelは枠さえ決まっていれば、多少中身が適当でもカッコがつきます。初期の作成コストは意外と低く、縦横の枠を使って整理できる。ある意味、ロジカルシンキングができない人でもなんとなく構造化されたドキュメントができるという特徴があります。

Excelが悲惨なのは、2次改修や再利用。枠に収まらなくなって、ちょっとセルを調整したくなったりすると調整に時間がかかるという点です。また、四角とか丸とか絵を書いた場合も、ちょっと追加しよう、でも枠に収まらない(> <)ということになると、修正に手間がかかります。全ページ(横断)で印刷がしにくい。ワークシートの数が5を超えると閲覧性が落ちます。

そもそもExcelはドキュメント作成ツールではありません。表計算兼簡易データベース。CSVがあんまりにも貧弱というのはありますが、ある程度フォーマットの決まったデータをやり取りする中間フォーマットとしては結構便利だったりもします。また、使える人が多いのもメリットです。数値的なデータを要求されたら、Excel形式でとりあえず渡して置けば、集計とかはユーザが勝手にやってくれちゃったりします。

Wiki

自由自在に広がっていくことができます。WikiPediaでページを色々たどっているうちに、かなり時間をロスしてしまったという、経験をお持ちの人もいると思います。カオスな、複雑な情報も扱うことができます。いくらでも情報を結びつけて、深めていくことができます。

Wikiはトップダウンのツリー型ではなく、有機的な情報のネットワークである、セミラティス構造をしているという特徴があります。完全に、分類しにくい情報などを、そのまま入れていくことができます。例えば、次のようなデータがあったとします。

  • VW ゴルフトゥーラン
  • BMW 3シリーズ
  • ホンダ オデッセイ
  • 日産 スカイライン

例えば、セダン、ミニバン、というのを上位概念として置けば、ゴルフとオデッセイが同じ枠に、3シリーズとスカイラインが同じ枠に入ります。また、国産車か、輸入車か、という分類をすれば違う分類になります。ロジカルシンキングというのも、目的が変われば分類が変わります。Wikiであれば、そのまま入れてしまい、そこにリンクするページ(切り口)を複数用意する、ということも可能です。

一方、自由故に、文章の構成、内容の質などの統一性を図るのが難しいという欠点があります。WikiPediaのように、だれかが基本骨格を作って、その中に書いていく、などの対処が必要になってくるでしょう。そろそろ、Wiki従事者認定試験とかWiki管理者認定試験とかできてもいいころかと。

また、Webアプリケーションである、というのも、他とは異なります。

Sphinx

きとんとした背骨があり、大きく成長しても、基本骨格を維持しながら、骨の周りに肉付けがされて大きくなっていくことができます。体が大きくなっても、そのままの構造で大きくしていくことができる。骨格は決まっているので、Wikiとは違って、新しい情報をどこでも自由にぱっと追加することはできず、入れる位置を熟考する必要があります。また、基本骨格以外に、神経的なネットワークを追加していくことで、情報のナビゲーションのしやすさをどんどんと向上させていくことができます。

プレーンテキストなので、ツールを使って、差分をきれいに見ることが可能です。SVNでもgitでもhgでも、バージョン管理をしているのであれば、その環境に合わせることができます。ソースコードと一緒に入れて、同じ環境下でバージョン管理を行い、変更情報を合わせていくのがおすすめです。

成長しやすいドキュメントのヒミツ

Sphinxの「成長しやすいドキュメントの秘密」は、次の2点のポイントに分けられます。

  • 背骨
  • 神経のネットワーク

これらについて説明を行っていきます。

背骨

C言語だとincludeみたいな感じで、自分の子供を記述していきます。toctreeさえわかればSphinx初段です。toctreeは、ドキュメント中のセクションタイトルを拾ってきて、そこから目次を作成します。toctreeに対する操作を紹介します。

子供を追加

toctreeの中にファイル名(拡張子なし)を並べて行くと、それを書いた場所の直下に子供を並べることができます。ワイルドカードを利用することもできます。1ファイル中に複数のtoctreeを書くこともできますし、入れ子にしていくこともできます。サブディレクトリも指定できるので、ディレクトリ構造と合わせると、管理が楽になります。

.. toctree::

   child

toctreeの目次に内容を追加

ファイルの中にセクションタイトルを追加していけば、親ページのセクションタイトルも更新されます。セクションタイトルの階層が反映されますので、各ページの中で整理して書いていくと、親ページからも情報を探しやすくなります。

構造を変えずに子供の分割

1つのページが長くなりすぎてきたら、ファイルを後半と前半に分け、両方の名前をtoctreeに追加します。

子供の並び替え

toctreeはファイルの名前のポインタ情報なので、並び替えなどで簡単に入れ替えることができます。階層構造も大きく変える場合は、移動する単位で子供を分け、ディレクトリ構造に入れなおし、最後にtoctreeを配線し直します。最後に、ビルドした結果を見てみて、つなぎの文章を追加したり調整すればOKです。

つまみぐい勉強法という本でも、書きすぎた内容を削ったり、大幅に章構成を整理したり、ということを何度か行いましたが、結構短時間で行うことができました。

背骨の編集と各ページの変更を順番に行おう

全体構造を見る俯瞰視点(toctree)と、詳細を見て行く集中モードの、二つの視点を行き来しながら、どんどん書いていけます。俯瞰視点のおかげで、ロジカルツリー状の構造にすることができ、大分類から小分類へ、ということがきちんと整理できるようになります。目次だけ見てみたい場合には、まずはタイトルだけのページを作り、ツリーを眺めてみれば良いでしょう。

集中モードでは、単独のウェブページを作る感覚でどんどん書いていけますし、細かい情報の整理はファイルの中で完結しているため、いちいち全体構造に手を入れながら書いていく必要はありません。

この2つの視点を切り替えていくことで、さまざまなフィードバックを受けて、ドキュメントを改善していけます。ドキュメントの読みやすさには次の2種類があると思います。Sphinxであれば、この両方のメリットを持つ、ハイブリッドなドキュメントを作ることができます。本やWikiなどの場合は、絶対的な位置関係を把握しながら書いていく必要があります。

ロジカルツリー=紙的読みやすさ

  • 1つのセクションで1つのものを説明する
  • 大項目から小項目へのブレークダウン
  • 単語→ページ数による参照(索引)

ウェブ的な書きやすさ・読みやすさ

  • スクロールで閲覧、探索
  • リンクによるナビゲーション
  • 検索
  • ページ内の相対的な重み付け(セクション、サブセクション)
  • ページ内で独立して、導入、説明という入れ子構造にしやすい(雑誌的構造)

神経ネットワーク

神経は「痛みを伝える」などの、それぞれの目的に特化した情報の経路を提供しています。

Sphinxでは、意味情報(セマンティクス)を使って、情報をつなげて行くことができます。トップダウンの構造に追加して、意味的な情報の流れを追加していけます。

基本的には、説明ユニットと、目次の2つで構成されています。

説明ユニット

Pythonであれば、モジュール、クラス、関数、メソッド、変数などです。詳細説明部に項目の説明を書いておきます。説明書きます。

.. function:: open(filename[, mode])

   ファイルをオープンします。

実際にドキュメントの文章の中では次のように書きます。

ファイルのオープンには、 :func:`open` を使用します。

ビルドすると、文書の中から、詳細説明部へのリンクが張られます。文章を書くときも、意味を考えながら書くことになりますし、資料性の高い文章になります。

詳細説明部で使っている書き方が「ディレクティブ」、文章中の表記方法が「ロール」という文法になっています。

Sphinxでは、数多くの説明ユニットの種類が定義されています。また、各種プログラミング言語向けの拡張も作ることができます。また、簡易的なものであれば設定ファイルに1行足すことで、自分で種類を増やすこともできます。

Redisの翻訳の場合は、コマンドと設定名についての説明ユニットを追加しています。

目次

セクションタイトル、表などの前に

.. index:: 設定一覧

設定一覧
========

* no
* always
* everysec

目次に「設定一覧」という項目が出てくるようになります。きちんと定義していくと、分かりやすい目次を作っていくことができます。

ドキュメント作りがサクサク進むしかけ

例えば、Oracleであれば、リファレンス、パフォーマンスチューニング、バックアップ、コツ、構造設計など、さまざまな本が出ています。プログラミング言語の場合も、チュートリアル、言語仕様、ライブラリリファレンス、外部言語とのインタフェース、フレームワークの説明など、さまざまな種類の本があります。

本が扱える情報はごく一部。1冊あたり、1コンテンツと言われています。本を書くというと、「自由自在に自分の思いを書いていく」というイメージがありますが、実際に書いていると「これは内容から外れる」「これは内容が飛躍する」など、意外と自由がありません。

Sphinxが狙っているのは、百科事典です。Pythonのさまざまな種類(1つ1つが1冊ぐらいのボリューム)のドキュメントを取り扱うために作られたシステムでもありますので、本1冊程度のボリュームであれば余裕で扱えます。むしろ、機能が使い切れなくて寂しいぐらいに感じます。

Sphinxのドキュメント構造についていろいろ紹介しましたが、ドキュメントを成長させていくための作戦・考え方としては次の3種類あります。

部分部分から攻める

細かいまとまりで、1つずつファイルを作っていきます。モジュールごとに1つのreSTファイルを作り、その中でセクション構造を考えながらファイルを作ります。次に、ディレクトリに整理して、toctreeで各ドキュメントをつなげて行きます。

その後、足りない情報を足していったり、関連項目を集めてリファクタリングしていくなどして成長させて行きます。

全体像から攻める

まず、セクションタイトルを並べて、ビルドしてtoctreeの全体像を作っていきます。その後は中を埋めながら、ファイルが大きくなったら、ファイルを分割したりディレクトリに分けたりしながら成長させて行きます。

読みやすさを考えてコツコツ頑張る

索引、モジュールインデックスを見ながら、情報のカバレッジを上げて行きます。必要に応じてディレクトリを分け直したりしながら、構造を作り上げて行きます。