方が気になっていると思いますが、こちらもがんばって書きますよ!追記::がんばり過ぎて長くなりました。読み飛ばしそうな勢いです(w一気に書いたので、あんまり査読もしてないです。考えていることもあり、ブース説明員清水川さんの腰が引けるほど喰い付き良く喰いついちゃったことを覚えています。講演(講師は渋川さん、清水川さん、山口さんという豪華講師陣)をしていただきました。Sphinxが認知されてきたんじゃないかなぁとおもっています。はまっているかについて、そもそもドキュメント(文書)作成とはなんぞやという根本的なところから論考してみたいと思います。ドキュメント作成の過去、現在¶ドキュメント作成とはなんぞや、という事を考える前に、ドキュメント作成の過去と現在をふりかえってみました。蓄積目的など今日とあまり替わらない用途で使われていたようです。2世紀頃に中国で紙が発明され、7世紀に木版印刷、15世紀にグーテンブルクによる活版印刷、18世紀末に平板印刷がそれぞれ発明され、(主に出版目的での)定型ドキュメントの紙による大量作成への道筋を付けました。Pedia)Noteドキュメント作成(編集/出力)のうち、出力技術は18世紀末(約200年前)にはじめて一般化した!(出版目的以外の)個別ドキュメントを手書き以外で作成する方法は、19世紀後半(約150年前)にタイプライターが出現したのがおそらく最初でしょう。タイプライターには挿入削除という概念は無く、ミスをすると最初から全て入力しなおしでした。できるようになるのは一般的には20世紀末、個人向けワープロやパーソナルコンピュータが普及してからと考えて良いでしょう。Pedia)Noteドキュメント作成(編集/出力)のうち、編集技術は20世紀末(約20年前)にはじめて(出版目的以外で)一般化した!「編集」「出力」というドキュメント作成の両輪が手元に揃った1990年代以降、急速に作成されるドキュメントの量は増えていきます。HTMLオーサリングツールなど数多あるツールとキーボードというデバイスを通じて手で書いていました。ドキュメントを作成/編集するのは人間だったのです。人が手で書いたものを、機械(システム)が編集/変換してくれるようにしてきました。セマンティックWebにより、ドキュメントの各要素の全てを必ずしも自分で作る必要がなく、公開されているドキュメント要素を引用し、加工し、かつ人間だけなく機械がドキュメントをコンテキストや条件に従い自動生成するようになってきました。Noteドキュメント作成(編集/出力)のうち、出力技術は21世紀(約10年前)に自動処理が一般化した!いよいよドキュメント作成(編集/出力)に機械が参画するようになってきたのです。(XPathなどを含む)XML系技術に対して、アンチテーゼとして、誰でも気軽に使えるドキュメントフォーマットがいくつか出てきました。ある、と自分は認識しています。今日(主観的に)よく使われている構造化ドキュメントとパーサーの組み合わせとしては、下記があると思います。docutiles/Sphinxこれらパーサの多くは、パースの際に指定することで出力結果を変えることができます。人が書いた1つの構造化ドキュメントを、機械が適宜フォーマットにあわせて加工した上で出力してくれるようになってきたのです。Note構造化記法の選択肢が増えてきた。いう考え方が出てきた。手元(デスクトップなど)で手軽に実現できる。)ドキュメント作成における「編集」「出力」の両輪のうち、「出力」については機械が適宜やってくれる時代になりました。なると、次はドキュメント「編集(記述や推敲を含む)」をどう機械にやらせるか、が次の大きなトピックとなるでしょう。構造化されたドキュメントでは、全てを人が手で記述する必要は無く、人の手によらなければ作ることができない「主観ドキュメント」のセグメントと、システマティックに生成されるべき「客観ドキュメント」のセグメントを明確に分離し、それらをセマンティックな技術で編集することで、より軽い手間で、より正確で、より最新の情報を盛り込んだドキュメントを作ることが可能になるはずなのです。(だと思う)人は、むやみにドキュメント自体を電子媒体上に手書きするのではなく、まず、なにを人が書き、何を機械に書かせるのか設計してドキュメントを作成する、そんなステージにきているのです。いう前項の結論を受けて、じゃそもそもドキュメントを人はなぜ必要とするのか、という話題に入ります。必要とされないのであればそのドキュメント(とその自動生成)に工数を掛ける意味がないので、これは重要な論点です。ほとんど場合、下記の4つのいずれかの必要性(目的)からドキュメントが作成されます。参考:運用ドキュメントが必要な理由このうち、Level-3は人間の領域です。ないと人間の存在価値に疑問符がついちゃうので、そう考えています。一方で、Level-2以下は、全て自動化が可能とは思いませんが、レベルが低いほど、機械が担当する割合が高い領域だと考えています。Note各ドキュメント作成の必要性をまず明確にしよう。(必要性の低いドキュメントに工数を取られないようにする)その上で、そのドキュメントの必要性(目的)を明確にし、どの程度の割合で人と機械がドキュメント作成を分担するか決める。(そんな時代がたぶん来る)ドキュメントの価値¶さて、人と機械がドキュメント作成を分担することとして、どの部分を人が書き、どの部分を機械に書かせるべきでしょうか。一義的には、一定の規則性に基いてシステマティックに生成できるドキュメントは機械が書き、そうではないものは人が書くべきでしょう。それではいつまでたっても人が書くドキュメントは減りません。今後は視点を変えて、人は「人が作成することで費用対効果が大きいことが期待できるドキュメント」を作成し、そうではない「人が作成すると費用対効果が見合わないドキュメント」は機械に作成させる流れになるでしょう。Warning極論すると、「機械が作成しても費用対効果が見合わないドキュメント」は「作らない」ことになるでしょう。それは各ドキュメントの最大のステークスホルダーである「ドキュメントの利用者」と「ドキュメントの提供者」の視点からの2つの「価値」基準になると考えています。(利用者視点)¶まず、利用者視点で「ドキュメントの利用価値」が存在しないといけません。利用者の利用価値の無いドキュメントは、作成維持する意味がないからです。仮に利用者が(たとえ自分ひとりであっても)存在するのであれば、「いかに使われるか」という観点から、下記の3つの評価ベンチマークでその価値を評価できると考えています。2つを最大化させるためには何が必要か考えてみます。Availability)使いたい時に使える(反復利用できる)状態になってはじめて利用価値が生まれます。使いたいときにドキュメントを利用できないことで、利用価値が低減します。「可用性」は機械に担保させるべき領域だと考えています。Reliability)内容の間違いが最小限である(最新を維持する)ことで利用価値(信頼)が高まります。古い、誤りがある、などドキュメントが信頼できないことで、利用価値が低減します。Serviceability)再利用性を高め、ドキュメント数を増幅させることで、読者の利用機会を増大させることが可能となります。ドキュメントの維持保守ができない(提供機会の増大どころではない)と、利用価値が大きく低減します。影響し、そのドキュメントの最終利用価値を増加/低減させます。ついては、各情報の要素は機械が生成し、その情報に対する意味づけやドキュメントの幹となる部分は人が書くことで維持拡大していくことになるでしょう。その手法として、「利用価値のためのドキュメンテーションデザインパターン」と言うべきものが徐々に形作られていくのではないかと考えています。評価ベンチマークNote繰り返し使われ、寿命が長いほどドキュメントの利用価値は高い。(提供者視点)¶さて、利用価値が有意であると見込まれるのであれば、提供者側はドキュメントを作成しなくてはいけません。ドキュメント提供側でも、そのドキュメントの作成維持に無限のリソースを使用することはできないため、そのドキュメントの提供に関わる費用対効果が問われることになります。高さと、陳腐化の早さに着目し、資産性、費用性を評価することで判断できると考えています。持てる限りのリソースを注ぐことになるでしょう。(仮称)Noteドキュメントの提供価値は、そのドキュメントのテーマによる資産性(プラス)/費用性(マイナス)によって大きく影響を受ける。仮に会計的にこれらを分析した場合、「費用性ドキュメント」を人が作成した場合の費用対効果は、直接配賦ができない限りは「費用のみ存在」し「効果はゼロ」であり、「資産性ドキュメント」もしくは「収益性ドキュメント」を書かない限り、ドキュメント陳腐化の早さもあり、ドキュメント提供に対する費用対効果はプラス方向に行かない、ということになります。各ドキュメントの提供価値が明確になった(まだ難しい?)ところで、ようやくそのドキュメントの設計に着手します。はい、ドキュメントの構造設計です。構造化ドキュメントを書く上では避けられない部分ですね。今回の論考では、「構造化」を下記の通り定義します。構造化とは「ばらばらになっているものを、一定の基準に従い論理立てて整理すること」そして、ドキュメント構造は概ね、下記の3つの基本要素で構成されています。これは、現時点では他の構造化記法にはない特徴です。Warning定型メールなど短い定型書式などでは、YAMLの方が自然だと思います。おいては、ドキュメントの基本要素3点を下記の通り記述できます。自然に実現しています。ドキュメント全体のツリー構造化を実現しています。(管理もしているそうです)。記法は自然とは言い難いですが、マッチングによる自動処理(:glob:)などを比較的平易な書式で利用可能です。(Sphinx拡張)ラベルと解釈済みテキストロール(ref)を組み合わせて、これまた比較的平易な書式で記述可能です。記法は自然とは言い難いですが、その特性上、あまり目立たないところに記述されることが多いので、そんなに邪魔にはならないかなとおもっています。Note特に、クロスリファレンスが非常に簡単に利用できる点を個人的に高く評価しています。「普通のテキストっぽいのに構造化されたドキュメント」を書くことも、「ばりばりに構造化されたドキュメント」を書くこともできるのです。これは構造化ドキュメントを書くための敷居を大幅に下げる効果があります。やれる範囲で構造化しておいて、必要が出てきたときに後で直すことが容易にできる、かつやればやるだけその効果があるからです。Sphinxがもたらすもの¶ドキュメントの構造化には、抽象化能力が人にもドキュメントツールにも強く求められると考えています。人に求められる「抽象化能力」とは、"対象から注目すべき要素を重点的に抜き出し、他は無視する手法を適切に使いこなす能力"で、ドキュメンテーションでは非常に重要な能力です。全ての事象をドキュメントに記述することは事実上不可能であり、なんらかの取捨選択をした上で、効率的かつ理解しやすい形でドキュメントにまとめあげていかなければならないからです。ドキュメントツールに求められる「抽象化能力」とは、1つは機能や操作に特徴的な側面を取り出して扱いやすく提供すること、もう1つはその機能や操作において物理的な制約を内包せずに論理的な構造に常に追随すること、と個人的には捉えています。ここでは、この定義に従い、Sphinxがもたらす抽象化のメリットを列挙してみます。Note相対化と言うべきものも一部もありますが、ここでは無理に分類しません。「Sphinxのここが残念だよ問題」も思い出せる範囲で書いてみます。先のドキュメントに見出しがあると、include元の見出しとコンフリクトする。衝突問題)クロスリファレンスの指定リファレンス先のラベルとリファレンス元のrefロールは、指定されているラベル名が同一であれば、それぞれは同期を意識する必要がなく、ファイル構成が変更されてもbuildしなおせば自動的に追随してくれる。ドキュメント上にネットワーク構造を構築するのが非常に容易で、秀逸。リファレンス先として集中しているところが「情報の重心」のひとつになるはずだが、現状では標準のSphinxでクロスリファレンスの構成やラベルが重複しないように管理する機構がユーザには提供されていない。(toctree見える化問題)コンテンツの共通部品化(includeやliteralinclude)インクルード先のドキュメントがreSTであればパースしてくれる。include指定はパス指定なので、ファイル構造を変更すると大崩壊する。(ファイル単位のラベルって概念が必要そうだけど)多段includeすると、全てincludeの大元ファイルからのパスを見るので、普通にやると失敗する。多重インクルードができたので、復活させてほしい。階層的に構造化したい場合は必須なので。複数のSphinxドキュメントの境界を意識しなくて良くなる野心的な機能だと思っています。現状ではリンクのみ可能ということで、interincludeを是非実装していただきたい、と思っています。実装要望)InterIncludeが実現されると、Sphinxで作成して成長したドキュメントを好きなタイミングで分割する自由が得られるはず、なので。(ドキュメント分家方式の実現)ドキュメントの未来¶ドキュメントの今後を考える上で、作成工数の抑制と効率的な維持管理を実現するための「システマティックなドキュメント生成」という視点は極めて重要になっていくと思います。セマンティック技術の再評価、情報の「マッシュアップ」技法など、IT技術によるIT技術現場のためのドキュメント技術の実践拡大に非常に期待を持っています。非常に有望な位置に今いると思うのです。今後ドキュメントというものは、人がWhyを主体的に書き、機械が4W1H(What/When/Where/Who/How)のほとんどを与えられたコンテキストを元に記述していくことになると思います。人と機械が書いたものが、マッシュアップされることを前提にドキュメンテーションという活動は成立していくのだろうと考えています。業務自体はドキュメントドリブンという、本来あるべき姿で動いていくのだろうと思います。くりかえしになりますが、人は、むやみにドキュメント自体を電子媒体上に手書きするのではなく、まず、なにを人が書き、何を機械に書かせるのか設計してドキュメントを作成する、そんなステージに今きているのです。2011年11月)清水川さんとの共同セッション。Sphinxが主要テーマの一つでした。LastUpdate)今回の記事で引用しまくっていますが、自分なりに今年の年初にまとめたメモです。2012年1月)Sphinxを念頭に運用ドキュメントの構造化について論文発表しました。最後に¶いやー長かったですね(笑。読んだ人が10人でもいれば大満足です。機会があればコメントください(^_^。