================================================================ 2012-12-09 Sphinxから見えるドキュメント作成の過去、現在、未来 ================================================================ `Sphinx Advent Calendar 2012 `_ 9日目担当の `波田野 `_ ( `@tcsh `_ ) です。 昨日は `@shimizukawa `_ さんの `intersphinxを使おう #sphinxjp アドベントカレンダー2012 `_ でした。 たくさんの人でリレーするこのアドベントカレンダーよりも `Sphinx Advent Calendar 2012 (全部俺) `_ の方が気になっていると思いますが、こちらもがんばって書きますよ! 追記:: がんばり過ぎて長くなりました。 10人中9人は :ref:`最後 ` まで読み飛ばしそうな勢いです(w 一気に書いたので、あんまり査読もしてないです。スイマセン(^^; .. contents:: ---------------------------------------------------------------- 出会い ---------------------------------------------------------------- 2010年09月10日-11日に八王子で開催された `オープンソースカンファレンス `_ に `運用研究会 `_ として出展したのが、`Sphinx と @shimizukawa さんとの出会い `_ でした。 運用研究会では `運用にとって最も重要な基盤はドキュメントである `_ と考えていることもあり、ブース説明員清水川さんの腰が引けるほど喰い付き良く喰いついちゃったことを覚えています。 そして、3ヶ月後に `ドキュメントを作りたくなってしまう魔法のツール Sphinx `_ の講演(講師は渋川さん、清水川さん、山口さんという豪華講師陣)をしていただきました。 この時期以降、 `blockdiag `_ の普及とともに非プログラマ系エンジニア(業務系、運用系エンジニア)のみなさんに Sphinxが認知されてきたんじゃないかなぁとおもっています。 .. note:: 自分にとっても、この2つのイベントが Sphinx生活がはじまるきっかけとなり、今はどっぷりreSTを書いて make html する日々になっています:-) 今回は、なぜそこまでこのドキュメントツール "Sphinx" にはまっているかについて、そもそもドキュメント(文書)作成とはなんぞやという根本的なところから論考してみたいと思います。 ---------------------------------------------------------------- ドキュメント作成の過去、現在 ---------------------------------------------------------------- ドキュメント作成とはなんぞや、という事を考える前に、ドキュメント作成の過去と現在をふりかえってみました。 ドキュメント作成の過去 (手書き時代) ************************************** 現存する世界最古のドキュメントは紀元前3300年頃(約5300年前)にシュメール文明で作られた粘土板文書で、データ保管、契約書、公文書、知識の蓄積目的など今日とあまり替わらない用途で使われていたようです。 2世紀頃に中国で紙が発明され、7世紀に木版印刷、15世紀にグーテンブルクによる活版印刷、18世紀末に平板印刷がそれぞれ発明され、(主に出版目的での)定型ドキュメントの紙による大量作成への道筋を付けました。 参考: - `粘土板 (WiKi Pedia) `_ - `印刷 (WiKi Pedia) `_ .. note:: ドキュメント作成(編集/出力)のうち、出力技術は18世紀末(約200年前)にはじめて一般化した! (出版目的以外の)個別ドキュメントを手書き以外で作成する方法は、19世紀後半(約150年前)にタイプライターが出現したのがおそらく最初でしょう。 タイプライターには挿入削除という概念は無く、ミスをすると最初から全て入力しなおしでした。 ドキュメント入力後に挿入削除を含む "編集" ができるようになるのは一般的には20世紀末、個人向けワープロやパーソナルコンピュータが普及してからと考えて良いでしょう。 参考: - `タイプライター (WiKi Pedia) `_ .. note:: ドキュメント作成(編集/出力)のうち、編集技術は20世紀末(約20年前)にはじめて(出版目的以外で)一般化した! 「編集」「出力」というドキュメント作成の両輪が手元に揃った1990年代以降、急速に作成されるドキュメントの量は増えていきます。 ただし、単に手書き(もしくはタイプライター)のアウトプット(印刷)が電子化されて編集や再利用可能となったのみで、人々は、一太郎、Word、Excel、PowerPoint やHTMLオーサリングツールなど数多あるツールとキーボードというデバイスを通じて手で書いていました。 あくまでもドキュメントを作成/編集するのは人間だったのです。 .. warning:: 一部、先進的な人々は、技術文書を中心に roff や TeX などで、人が手で書いたものを、機械(システム)が編集/変換してくれるようにしてきました。 (SGMLは...) ドキュメント作成の過去 (自動化黎明期) **************************************** この状況に劇的な変化を与えたのが、2000年代初頭に爆発的に普及した XML および 周辺技術を使ったマッシュアップ、その上位概念としての "セマンティックWeb" だったと思います。 セマンティックWebにより、ドキュメントの各要素の全てを必ずしも自分で作る必要がなく、公開されているドキュメント要素を引用し、加工し、かつ人間だけなく機械がドキュメントをコンテキストや条件に従い自動生成するようになってきました。 .. note:: ドキュメント作成(編集/出力)のうち、出力技術は21世紀(約10年前)に自動処理が一般化した! いよいよドキュメント作成(編集/出力)に機械が参画するようになってきたのです。 ドキュメント作成の現在 ******************************** 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つの構造化ドキュメントを、機械が適宜フォーマットにあわせて加工した上で出力してくれるようになってきたのです。 .. note:: 構造化記法の選択肢が増えてきた。1ソース マルチアウトプット という考え方が出てきた。 (特にSphinx は手元(デスクトップなど)で手軽に実現できる。) ドキュメント作成における「編集」「出力」の両輪のうち、「出力」については機械が適宜やってくれる時代になりました。 となると、次はドキュメント「編集(記述や推敲を含む)」をどう機械にやらせるか、が次の大きなトピックとなるでしょう。 構造化されたドキュメントでは、全てを人が手で記述する必要は無く、人の手によらなければ作ることができない「主観ドキュメント」のセグメントと、システマティックに生成されるべき「客観ドキュメント」のセグメントを明確に分離し、それらをセマンティックな技術で編集することで、より軽い手間で、より正確で、より最新の情報を盛り込んだドキュメントを作ることが可能になるはずなのです。 .. note:: ドキュメント作成(編集/出力)のうち、編集技術は21世紀第1四半世紀(これから10年くらい)で自動処理が急激に一般化するはず (だと思う) 人は、むやみにドキュメント自体を電子媒体上に手書きするのではなく、まず、なにを人が書き、何を機械に書かせるのか設計してドキュメントを作成する、そんなステージにきているのです。(たぶん) ---------------------------------------------------------------- なぜ人はドキュメントを書くのか ---------------------------------------------------------------- **ドキュメント作成について、今後は構造化を意識して、なるべく人が手を下さずに書きましょう** と、いう前項の結論を受けて、じゃそもそもドキュメントを人はなぜ必要とするのか、という話題に入ります。 必要とされないのであればそのドキュメント(とその自動生成)に工数を掛ける意味がないので、これは重要な論点です。 ほとんど場合、下記の4つのいずれかの必要性(目的)からドキュメントが作成されます。 ドキュメントの必要性(目的)レベル - Level-0: 「記録のために」(ドキュメントの本質的な機能) - Level-1: 「整理のために」 - Level-2: 「客観化のために」 - Level-3: 「脱属人化(普遍化)のために」 参考: - `運用ドキュメントが必要な理由 `_ このうち、Level-3は人間の領域です。そうじゃないと人間の存在価値に疑問符がついちゃうので、そう考えています。一方で、Level-2以下は、全て自動化が可能とは思いませんが、レベルが低いほど、機械が担当する割合が高い領域だと考えています。 .. warning ドキュメントの目的レベルが高いほど、書き手の個性(能力を含む)が色濃く出るため、自動化などの機械化が難しい(仮説)。 .. note:: 各ドキュメント作成の必要性をまず明確にしよう。 (必要性の低いドキュメントに工数を取られないようにする) その上で、そのドキュメントの必要性(目的)を明確にし、どの程度の割合で人と機械がドキュメント作成を分担するか決める。 (そんな時代がたぶん来る) ---------------------------------------------------------------- ドキュメントの価値 ---------------------------------------------------------------- さて、人と機械がドキュメント作成を分担することとして、どの部分を人が書き、どの部分を機械に書かせるべきでしょうか。 一義的には、一定の規則性に基いてシステマティックに生成できるドキュメントは機械が書き、そうではないものは人が書くべきでしょう。正論です。 ただ、それではいつまでたっても人が書くドキュメントは減りません。 今後は視点を変えて、人は「人が作成することで費用対効果が大きいことが期待できるドキュメント」を作成し、そうではない「人が作成すると費用対効果が見合わないドキュメント」は機械に作成させる流れになるでしょう。 .. warning:: 極論すると、「機械が作成しても費用対効果が見合わないドキュメント」は「作らない」ことになるでしょう。 では、そのための判断基準はどんなものになるのか? それは各ドキュメントの最大のステークスホルダーである「ドキュメントの利用者」と「ドキュメントの提供者」の視点からの2つの「価値」基準になると考えています。 2つの「ドキュメントの価値基準」 - ドキュメントの利用価値 (利用者視点) - ドキュメントの提供価値 (提供者視点) ドキュメントの利用価値 (利用者視点) ************************************* まず、利用者視点で「ドキュメントの利用価値」が存在しないといけません。利用者の利用価値の無いドキュメントは、作成維持する意味がないからです。 仮に利用者が(たとえ自分ひとりであっても)存在するのであれば、「いかに使われるか」という観点から、下記の3つの評価ベンチマークでその価値を評価できると考えています。 ドキュメントの利用価値ベンチマーク 1. 読者の範囲 - 水平方向: 社会的範囲 (特定現場 〜 不特定多数) - 垂直方向: 社会的地位 (専門層/経営層 〜 一般層) 2. 参照回数 3. 利用期間(寿命) 1の「読者の範囲」は外的要素による影響が大きいため、ここでは「参照回数」、「利用期間」の2つを最大化させるためには何が必要か考えてみます。 反復利用できること (可用性 Availability) - 使いたい時に使える(反復利用できる)状態になってはじめて利用価値が生まれます。 - 使いたいときにドキュメントを利用できないことで、利用価値が低減します。 - 「可用性」は機械に担保させるべき領域だと考えています。 内容が信頼できること (信頼性 Reliability) - 内容の間違いが最小限である(最新を維持する)ことで利用価値(信頼)が高まります。 - 古い、誤りがある、などドキュメントが信頼できないことで、利用価値が低減します。 利用機会を増大できること (保守性 Serviceability) - 再利用性を高め、ドキュメント数を増幅させることで、読者の利用機会を増大させることが可能となります。 - ドキュメントの維持保守ができない(提供機会の増大どころではない)と、利用価値が大きく低減します。 これら3要素は、直接間接的に参照回数、利用期間に影響し、そのドキュメントの最終利用価値を増加/低減させます。 このうち「ドキュメントの利用価値」の本質とも言うべき「信頼性」「保守性」については、各情報の要素は機械が生成し、その情報に対する意味づけやドキュメントの幹となる部分は人が書くことで維持拡大していくことになるでしょう。 そしてその手法として、「利用価値のためのドキュメンテーションデザインパターン」と言うべきものが徐々に形作られていくのではないかと考えています。 参考: - `運用ドキュメントの利用価値 評価ベンチマーク `_ .. note:: - 繰り返し使われ、寿命が長いほどドキュメントの利用価値は高い。 - その利用価値は「機械が各情報の要素を生成と整合性を確保し、人が意味付けや幹を作る」という分担により「ドキュメントが常に最新で正確である」ことを保つことで維持拡大する (というイメージ) ドキュメントの提供価値 (提供者視点) ************************************* さて、利用価値が有意であると見込まれるのであれば、提供者側はドキュメントを作成しなくてはいけません。 しかし、ドキュメント提供側でも、そのドキュメントの作成維持に無限のリソースを使用することはできないため、そのドキュメントの提供に関わる費用対効果が問われることになります。 その費用対効果は、反復利用、再利用性の高さと、陳腐化の早さに着目し、資産性、費用性を評価することで判断できると考えています。 ここは長くなるので、詳細は下記の "参考" に譲りますが、「費用性ドキュメント」は機械に作らせて、人は「資産性ドキュメント」や「収益性ドキュメント」など **費用対効果が適切に見こめるドキュメントの作成** に持てる限りのリソースを注ぐことになるでしょう。 参考: - `運用ドキュメントの提供価値 (費用対効果) `_ - `SCA分析 (仮称) `_ .. note:: - ドキュメントの提供価値は、そのドキュメントのテーマによる資産性(プラス)/費用性(マイナス)によって大きく影響を受ける。 - 仮に会計的にこれらを分析した場合、「費用性ドキュメント」を人が作成した場合の費用対効果は、直接配賦ができない限りは「費用のみ存在」し「効果はゼロ」であり、「資産性ドキュメント」もしくは「収益性ドキュメント」を書かない限り、ドキュメント陳腐化の早さもあり、ドキュメント提供に対する費用対効果はプラス方向に行かない、ということになります。(あくまでも比喩ですが) ---------------------------------------------------------------- ドキュメントの構造化 (ドキュメント設計) ---------------------------------------------------------------- 各ドキュメントの提供価値が明確になった(まだ難しい?)ところで、ようやくそのドキュメントの設計に着手します。 はい、ドキュメントの構造設計です。構造化ドキュメントを書く上では避けられない部分ですね。 ドキュメント構造化とは ******************************** 今回の論考では、「構造化」を下記の通り定義します。 構造化とは 「ばらばらになっているものを、一定の基準に従い論理立てて整理すること」 そして、ドキュメント構造は概ね、下記の3つの基本要素で構成されています。 基本要素1. 見出し 文章ブロック単位での意味付け (単位情報のオブジェクト化) 基本要素2. 目次 読み手が認識しやすい位置への文章ブロックの格納 (ツリー構造(多分木)による構造表現化) 基本要素3. クロスリファレンス 文章ブロック間の関係付け (情報間ネットワーク構造の表現化) ここも長くなるので詳細は下記に譲ります(笑 参考: - `ドキュメントの構造化 `_ ドキュメント構造化とSphinx ******************************** 勘の良い人であればすぐに気付いたと思いますが、前項の「ドキュメントの基本要素」3つを比較的自然かつ平易な記法で構造化できるのが Sphinx の利用を前提とした reST (reSTructured Text) です。 繰り返しいろいろな人に言いまくっているのですが、Sphinx(reST)の特筆すべき特徴は **普通のテキストに見えるのに、比較的違和感を与えないままに構造化ドキュメントにすることができる!!** これは、現時点では他の構造化記法にはない特徴です。 .. warning:: 定型メールなど短い定型書式などでは、YAMLの方が自然だと思います。 Sphinx においては、ドキュメントの基本要素3点を下記の通り記述できます。 基本要素1. 見出し (reST標準) Section Structure(同一記号を見出しの下に連続して記述) で極めて自然に実現しています。 基本要素2. 目次 (Sphinx拡張) toctree でドキュメント全体のツリー構造化を実現しています。(管理もしているそうです)。 記法は自然とは言い難いですが、マッチングによる自動処理(:glob:)などを比較的平易な書式で利用可能です。 基本要素3. クロスリファレンス (Sphinx拡張) ラベルと解釈済みテキストロール(ref)を組み合わせて、これまた比較的平易な書式で記述可能です。 記法は自然とは言い難いですが、その特性上、あまり目立たないところに記述されることが多いので、そんなに邪魔にはならないかなとおもっています。 .. note:: 特に、クロスリファレンスが非常に簡単に利用できる点を個人的に高く評価しています。 **Sphinx(reST) は、「普通のテキストっぽいのに構造化されたドキュメント」を書くことも、「ばりばりに構造化されたドキュメント」を書くこともできるのです。これは構造化ドキュメントを書くための敷居を大幅に下げる効果があります。なぜなら、やれる範囲で構造化しておいて、必要が出てきたときに後で直すことが容易にできる、かつやればやるだけその効果があるからです。** ---------------------------------------------------------------- Sphinxがもたらすもの ---------------------------------------------------------------- ドキュメントの構造化には、抽象化能力が人にもドキュメントツールにも強く求められると考えています。 人に求められる「抽象化能力」とは、"対象から注目すべき要素を重点的に抜き出し、他は無視する手法を適切に使いこなす能力"で、ドキュメンテーションでは非常に重要な能力です。 なぜなら、全ての事象をドキュメントに記述することは事実上不可能であり、なんらかの取捨選択をした上で、効率的かつ理解しやすい形でドキュメントにまとめあげていかなければならないからです。 ドキュメントツールに求められる「抽象化能力」とは、1つは機能や操作に特徴的な側面を取り出して扱いやすく提供すること、もう1つはその機能や操作において物理的な制約を内包せずに論理的な構造に常に追随すること、と個人的には捉えています。 ここでは、この定義に従い、Sphinxがもたらす抽象化のメリットを列挙してみます。 .. note:: - 相対化と言うべきものも一部もありますが、ここでは無理に分類しません。 - 「Sphinxのここが残念だよ問題」も思い出せる範囲で書いてみます。 見出しの指定 コンテキストによって自動的にレベルを判断してくれる - ただし、include 先のドキュメントに見出しがあると、include元の見出しとコンフリクトする。これがかなり残念 **(Section Structure 衝突問題)** クロスリファレンスの指定 リファレンス先のラベルとリファレンス元のrefロールは、指定されているラベル名が同一であれば、それぞれは同期を意識する必要がなく、ファイル構成が変更されてもbuildしなおせば自動的に追随してくれる。 ドキュメント上にネットワーク構造を構築するのが非常に容易で、秀逸。 - リファレンス先として集中しているところが「情報の重心」のひとつになるはずだが、現状では標準のSphinxでクロスリファレンスの構成やラベルが重複しないように管理する機構がユーザには提供されていない。 **(toctree見える化問題)** コンテンツの共通部品化(includeやliteralinclude) インクルード先のドキュメントがreSTであればパースしてくれる。 - ただし、include指定はパス指定なので、ファイル構造を変更すると大崩壊する。 **(include 抽象化問題)** - refロール同様に、ファイル構造が変更されても自動的に追随するような include がほしい。(ファイル単位のラベルって概念が必要そうだけど) - 多段includeすると、全てincludeの大元ファイルからのパスを見るので、普通にやると失敗する。 **(多段 include ができない問題)** - たしか、1.0.7 くらいまでの literalinclude では多重インクルードができたので、復活させてほしい。 - 特に階層的に構造化したい場合は必須なので。 InterSphinx `まだつかったことない `_ のですが、複数のSphinxドキュメントの境界を意識しなくて良くなる野心的な機能だと思っています。 - 現状ではリンクのみ可能ということで、interincludeを是非実装していただきたい、と思っています。 **(InterInclude 実装要望)** - InterIncludeが実現されると、Sphinxで作成して成長したドキュメントを好きなタイミングで分割する自由が得られるはず、なので。(ドキュメント分家方式の実現) ---------------------------------------------------------------- ドキュメントの未来 ---------------------------------------------------------------- ドキュメントの今後を考える上で、作成工数の抑制と効率的な維持管理を実現するための「システマティックなドキュメント生成」という視点は極めて重要になっていくと思います。 そして、セマンティック技術の再評価、情報の「マッシュアップ」技法など、IT技術によるIT技術現場のためのドキュメント技術の実践拡大に非常に期待を持っています。 その実践技術の一つとして Sphinx が非常に有望な位置に今いると思うのです。 今後ドキュメントというものは、人がWhyを主体的に書き、機械が4W1H(What/When/Where/Who/How)のほとんどを与えられたコンテキストを元に記述していくことになると思います。 そして人と機械が書いたものが、マッシュアップされることを前提にドキュメンテーションという活動は成立していくのだろうと考えています。 更に、業務自体はドキュメントドリブンという、本来あるべき姿で動いていくのだろうと思います。 くりかえしになりますが、人は、むやみにドキュメント自体を電子媒体上に手書きするのではなく、まず、なにを人が書き、何を機械に書かせるのか設計してドキュメントを作成する、そんなステージに今きているのです。(そんな実践をしている人がいれば飛んで話を聞きにいきたい今日この頃) .. note:: ドキュメント作成(編集/出力)のうち、編集技術は21世紀第1四半世紀(これから10年くらい)で自動処理が急激に一般化するはず (だと思う、と繰り返してみる) ---------------------------------------------------------------- 関連資料 ---------------------------------------------------------------- - `運用ドキュメント2011～手軽にスピーディに継続的に保守するためのツール入門～ `_ (Internet Week 2011 / 2011年11月) - **清水川さんとの共同セッション。Sphinxが主要テーマの一つでした。** - 当日の `プレゼンテーション資料 `_ も公開されています。 - `Operation Document Model `_ (2012-01-09 LastUpdate) - **今回の記事で引用しまくっていますが、自分なりに今年の年初にまとめたメモです。** - `Sphinx Advent Calendar 2012 6日目の記事 Sphinx と MeCAB でナレッジベース風ツールを作る `_ (GoingMyNetさん)の記事中で言及いただきました! さんきゅ! - `運用ドキュメントの分類と構造化 `_ (電子情報通信学会 インターネットアーキテクチャ研究会 2011年度第6回研究会 / 2012年1月) - **Sphinxを念頭に運用ドキュメントの構造化について論文発表しました。** .. _end_20121219: ---------------------------------------------------------------- 最後に ---------------------------------------------------------------- いやー長かったですね(笑。ちゃんと読んだ人が10人でもいれば大満足です。 機会があればコメントください(^_^。 明日は `Sphinx Advent Calendar 2012 (全部俺) `_ の `@usaturn `_ さんです。 自分と似た環境(Sphinx初心者&プログラマーではない&インフラ出身)の方の発表なので、ものすごく楽しみです!