ドキュメント作成の過去 (手書き時代)¶

現存する世界最古のドキュメントは紀元前3300年頃(約5300年前)にシュメール文明で作られた粘土板文書で、データ保管、契約書、公文書、知識の蓄積目的など今日とあまり替わらない用途で使われていたようです。

2世紀頃に中国で紙が発明され、7世紀に木版印刷、15世紀にグーテンブルクによる活版印刷、18世紀末に平板印刷がそれぞれ発明され、(主に出版目的での)定型ドキュメントの紙による大量作成への道筋を付けました。

参考:

• 粘土板 (WiKi Pedia)
• 印刷 (WiKi Pedia)

(出版目的以外の)個別ドキュメントを手書き以外で作成する方法は、19世紀後半(約150年前)にタイプライターが出現したのがおそらく最初でしょう。

タイプライターには挿入削除という概念は無く、ミスをすると最初から全て入力しなおしでした。 ドキュメント入力後に挿入削除を含む "編集" ができるようになるのは一般的には20世紀末、個人向けワープロやパーソナルコンピュータが普及してからと考えて良いでしょう。

参考:

• タイプライター (WiKi Pedia)

「編集」「出力」というドキュメント作成の両輪が手元に揃った1990年代以降、急速に作成されるドキュメントの量は増えていきます。 ただし、単に手書き(もしくはタイプライター)のアウトプット(印刷)が電子化されて編集や再利用可能となったのみで、人々は、一太郎、Word、Excel、PowerPoint やHTMLオーサリングツールなど数多あるツールとキーボードというデバイスを通じて手で書いていました。

あくまでもドキュメントを作成/編集するのは人間だったのです。

ドキュメント作成の過去 (自動化黎明期)¶

この状況に劇的な変化を与えたのが、2000年代初頭に爆発的に普及した XML および 周辺技術を使ったマッシュアップ、その上位概念としての "セマンティックWeb" だったと思います。

セマンティックWebにより、ドキュメントの各要素の全てを必ずしも自分で作る必要がなく、公開されているドキュメント要素を引用し、加工し、かつ人間だけなく機械がドキュメントをコンテキストや条件に従い自動生成するようになってきました。

いよいよドキュメント作成(編集/出力)に機械が参画するようになってきたのです。

ドキュメント作成の現在¶

Ajaxなどのドキュメントをマッシュアップする技術が普通に使われるようになった現在、肥大化した (XPathなどを含む)XML系技術に対して、アンチテーゼとして、誰でも気軽に使えるドキュメントフォーマットがいくつか出てきました。

1. XMLの複雑さを回避するもの
2. 人の可読性を重視するもの

1の代表的な例として JSON、2の代表的な例としてRubyコミュニティでよく使われている YAML (Yet Another Markup Language) が、Pythonコミュニティでよく使われている reST (reSTructured text) がある、と自分は認識しています。XMLを含むこれらのドキュメントフォーマットにより記述されたドキュメントは、それぞれの記法に従って構造情報を文書内に記述することから、 "構造化ドキュメント" と言われます。

今日(主観的に)よく使われている構造化ドキュメントとパーサーの組み合わせとしては、下記があると思います。

構造化ドキュメントとパーサーの組み合わせ例

• HTML + ブラウザ
• XML + XMLパーサ
• JSON + JSONパーサ
• YAML + YAMLパーサ
• reST + docutiles/Sphinx

これらパーサの多くは、パースの際に指定することで出力結果を変えることができます。 人が書いた1つの構造化ドキュメントを、機械が適宜フォーマットにあわせて加工した上で出力してくれるようになってきたのです。

ドキュメント作成における「編集」「出力」の両輪のうち、「出力」については機械が適宜やってくれる時代になりました。 となると、次はドキュメント「編集(記述や推敲を含む)」をどう機械にやらせるか、が次の大きなトピックとなるでしょう。

構造化されたドキュメントでは、全てを人が手で記述する必要は無く、人の手によらなければ作ることができない「主観ドキュメント」のセグメントと、システマティックに生成されるべき「客観ドキュメント」のセグメントを明確に分離し、それらをセマンティックな技術で編集することで、より軽い手間で、より正確で、より最新の情報を盛り込んだドキュメントを作ることが可能になるはずなのです。

人は、むやみにドキュメント自体を電子媒体上に手書きするのではなく、まず、なにを人が書き、何を機械に書かせるのか設計してドキュメントを作成する、そんなステージにきているのです。(たぶん)

ドキュメントの利用価値 (利用者視点)¶

まず、利用者視点で「ドキュメントの利用価値」が存在しないといけません。利用者の利用価値の無いドキュメントは、作成維持する意味がないからです。

仮に利用者が(たとえ自分ひとりであっても)存在するのであれば、「いかに使われるか」という観点から、下記の3つの評価ベンチマークでその価値を評価できると考えています。

ドキュメントの利用価値ベンチマーク

1. 読者の範囲

• 水平方向: 社会的範囲 (特定現場 〜 不特定多数)
• 垂直方向: 社会的地位 (専門層/経営層 〜 一般層)

2. 参照回数
3. 利用期間(寿命)

1の「読者の範囲」は外的要素による影響が大きいため、ここでは「参照回数」、「利用期間」の2つを最大化させるためには何が必要か考えてみます。

反復利用できること (可用性 Availability)

• 使いたい時に使える(反復利用できる)状態になってはじめて利用価値が生まれます。
• 使いたいときにドキュメントを利用できないことで、利用価値が低減します。
• 「可用性」は機械に担保させるべき領域だと考えています。

内容が信頼できること (信頼性 Reliability)

• 内容の間違いが最小限である(最新を維持する)ことで利用価値(信頼)が高まります。
• 古い、誤りがある、などドキュメントが信頼できないことで、利用価値が低減します。

利用機会を増大できること (保守性 Serviceability)

• 再利用性を高め、ドキュメント数を増幅させることで、読者の利用機会を増大させることが可能となります。
• ドキュメントの維持保守ができない(提供機会の増大どころではない)と、利用価値が大きく低減します。

これら3要素は、直接間接的に参照回数、利用期間に影響し、そのドキュメントの最終利用価値を増加/低減させます。

このうち「ドキュメントの利用価値」の本質とも言うべき「信頼性」「保守性」については、各情報の要素は機械が生成し、その情報に対する意味づけやドキュメントの幹となる部分は人が書くことで維持拡大していくことになるでしょう。 そしてその手法として、「利用価値のためのドキュメンテーションデザインパターン」と言うべきものが徐々に形作られていくのではないかと考えています。

参考:

• 運用ドキュメントの利用価値 評価ベンチマーク

ドキュメントの提供価値 (提供者視点)¶

さて、利用価値が有意であると見込まれるのであれば、提供者側はドキュメントを作成しなくてはいけません。 しかし、ドキュメント提供側でも、そのドキュメントの作成維持に無限のリソースを使用することはできないため、そのドキュメントの提供に関わる費用対効果が問われることになります。

その費用対効果は、反復利用、再利用性の高さと、陳腐化の早さに着目し、資産性、費用性を評価することで判断できると考えています。

ここは長くなるので、詳細は下記の "参考" に譲りますが、「費用性ドキュメント」は機械に作らせて、人は「資産性ドキュメント」や「収益性ドキュメント」など 費用対効果が適切に見こめるドキュメントの作成 に持てる限りのリソースを注ぐことになるでしょう。

参考:

• 運用ドキュメントの提供価値 (費用対効果)
• SCA分析 (仮称)

ドキュメント構造化とは¶

今回の論考では、「構造化」を下記の通り定義します。

構造化とは

「ばらばらになっているものを、一定の基準に従い論理立てて整理すること」

そして、ドキュメント構造は概ね、下記の3つの基本要素で構成されています。

基本要素1. 見出し

文章ブロック単位での意味付け (単位情報のオブジェクト化)

基本要素2. 目次

読み手が認識しやすい位置への文章ブロックの格納 (ツリー構造(多分木)による構造表現化)

基本要素3. クロスリファレンス

文章ブロック間の関係付け (情報間ネットワーク構造の表現化)

ここも長くなるので詳細は下記に譲ります(笑

参考:

• ドキュメントの構造化

ドキュメント構造化とSphinx¶

勘の良い人であればすぐに気付いたと思いますが、前項の「ドキュメントの基本要素」3つを比較的自然かつ平易な記法で構造化できるのが Sphinx の利用を前提とした reST (reSTructured Text) です。

繰り返しいろいろな人に言いまくっているのですが、Sphinx(reST)の特筆すべき特徴は 普通のテキストに見えるのに、比較的違和感を与えないままに構造化ドキュメントにすることができる!! これは、現時点では他の構造化記法にはない特徴です。

Sphinx においては、ドキュメントの基本要素3点を下記の通り記述できます。

基本要素1. 見出し (reST標準)

Section Structure(同一記号を見出しの下に連続して記述) で極めて自然に実現しています。

基本要素2. 目次 (Sphinx拡張)

toctree でドキュメント全体のツリー構造化を実現しています。(管理もしているそうです)。 記法は自然とは言い難いですが、マッチングによる自動処理(:glob:)などを比較的平易な書式で利用可能です。

基本要素3. クロスリファレンス (Sphinx拡張)

ラベルと解釈済みテキストロール(ref)を組み合わせて、これまた比較的平易な書式で記述可能です。 記法は自然とは言い難いですが、その特性上、あまり目立たないところに記述されることが多いので、そんなに邪魔にはならないかなとおもっています。

Sphinx(reST) は、「普通のテキストっぽいのに構造化されたドキュメント」を書くことも、「ばりばりに構造化されたドキュメント」を書くこともできるのです。これは構造化ドキュメントを書くための敷居を大幅に下げる効果があります。なぜなら、やれる範囲で構造化しておいて、必要が出てきたときに後で直すことが容易にできる、かつやればやるだけその効果があるからです。