Word¶

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

• 縦書きに対応。知り合いの小説家の人はWordを使っていました。

• 日本語の文法チェックをしてくれます。商業レベルの文章を書くときに利用したり。

• 単語単位の差分機能。編集の人と、変更箇所や指摘をやりとりする際に便利でした。

• 論文、小説など、大きく構造を並び替えたりせず、文章の位置関係が比較的早期に決まるような長文の文章には適しています。

• 参考文献とか索引も作れます。あとは差し込み印刷などもできます。

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

Excel¶

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

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

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

Wiki¶

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

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

• VW ゴルフトゥーラン

• BMW 3シリーズ

• ホンダオデッセイ

• 日産スカイライン

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

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

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

Sphinx¶

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

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

背骨¶

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

.. toctree::

   child

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

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

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

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

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

• １つのセクションで１つのものを説明する

• 大項目から小項目へのブレークダウン

• 単語→ページ数による参照(索引)

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

• スクロールで閲覧、探索

• リンクによるナビゲーション

• 検索

• ページ内の相対的な重み付け（セクション、サブセクション）

• ページ内で独立して、導入、説明という入れ子構造にしやすい（雑誌的構造）

神経ネットワーク¶

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

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

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

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

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

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

.. index:: 設定一覧

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

* no
* always
* everysec

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

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

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

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

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