情報アーキテクチャとDITAテクノロジー。 Yandexでの講義に基づく

Darwin Information Typing Architecture（DITA）-技術文書に関連するプロセスを自動化するXMLテクノロジー。 DITAは長年にわたり、多数の多様な機能、コンテンツを整理するためのアプローチ、およびそれらの実装のための特定のメカニズムを蓄積してきました。 それらに戸惑うことは不思議ではなく、これはしばしばドキュメント自動化のための理解できない、効果がなく、単に不便なソリューションの出現につながります。 会社「哲学者」ミハイル・オストロゴルスキーのプロジェクトディレクターは、すべてを棚に置きます。

まえがき

提案された記事は、 Hyperbatonsの 1つについて著者が作成した短いレポートに基づいています。 話者としての自分に不満を感じるというわけではありませんが、この場合、口語の逐語的な転写を公開することは私の考えでは良い考えではありません。



まず、技術的なトピックに関するテキストには特定のデザインが必要です。 リスト、表、図、コードフラグメントが必要です。 しかし、私はテーブルで話す方法を知りません、そして、リストはスライドにうまく合いません。 第二に、2か月でレポートの内容をよく説明する例を準備することができましたが、今は使用しないのは奇妙です。 したがって、この記事は、口頭報告への重要かつかなり膨大な追加としてみなされ、変換された転写としてではないことをお願いします。



結論として、私はYandexの同僚に、口頭だけでなく書面でもこのような幅広い聴衆に連絡する機会を与えてくれたことに心から感謝しています。 これらの資料が関心のある専門家や技術管理者に役立つことを願っています。

ツールとタスク。 いいえ、その逆

DITAテクノロジーの作成者は、機能の広範なレパートリーを提供しています。 技術的には、これらの機能は、DITAマークアップ言語とDITA Open Toolkitソフトウェアパッケージで実装されます。DITAOpen Toolkitソフトウェアパッケージは、入力素材を （ コンテンツを呼び出し続けます ）1つまたは別の人間が読める形式に変換するように設計されています。 さらに、これらの機能は、サードパーティのソフトウェア製品によってより良くも悪くもサポートされます。 このようなサポートは、XMLエディターおよびコンテンツ管理システムで特に必要とされるため、今日では、このクラスのあらゆる開発ソフトウェア製品に含まれています。



機能の豊富さは、あらゆる技術の明らかな利点であると思われます。 しかし、彼と二人きりになった私たちは、高価なレストランでのディナーパーティーに最初に招待された人の立場にいることに気付きます。 なじみのない料理、多くの異なる同時にフォークとナイフ。 明確ではないものは何ですか。







レストランといえば。 それらのテーブルは通常、料理の順番に従って提供されます。 最初に提供されたのは、外部のデバイスのペア、次のデバイス-それに囲まれたデバイスなどです。プレートの後ろに置かれたデバイスをどう処理するかは明確ではありません。 したがって、重要な技術を習得するには、ツールからではなく、タスクから始める方が良いでしょう。 最初に「ランチ」メニューを調べて、それぞれの「料理」が何であるかを把握し、次に、適切なフォークから適切な方法で取り組む方法を学びます。

情報アーキテクチャの概念

DITAテクノロジーは、ソース素材の複数のブロックから出力ドキュメントを組み立てるように設計された多くの機能を備えています。 ただし、これらのブロックが正常に選択され、正しく接続されている場合にのみメリットがあります。



各ドキュメンテーションプロジェクトの独自性にもかかわらず、著者がその管理中に解決することを余儀なくされる構造的な問題は、一般的によく知られています。 後者により、材料を分解できるため、これらの問題の解決策は自動化に役立ちます。



情報アーキテクチャとは、特定のプロジェクトまたは製品用に選択された材料分解の方法を指します。 もちろん、この分解は、該当するテクノロジーによって提供されるアセンブリ機能に基づいて実行する必要があります。 ここではDITAテクノロジーに焦点を当てますが、他のテクノロジーについてはこの原則は変わりません。

マテリアルプレゼンテーションの統合

情報アーキテクチャによって解決策を提供する必要がある構造上の問題の重要な部分は、異なる文書または同じ文書内の同じテキストの繰り返しに関連しています。 このような繰り返しは、文化的伝統と人間の知覚の特性によるものであるため、それらを放棄することはできません。



繰り返しのためにマニュアルを手動で準備する場合、高額を支払う必要があります。

• 著者の負荷が増加し、人件費が増加します。
• ドキュメントを更新すると、エラーが蓄積されます。

一意でないテキストに変更を加えると、資料全体の完全なチェックと各繰り返しの同様の改訂につながるという事実により、エラーが発生します。 十分な量の材料では、この操作を必要な精度で実行することはほとんど不可能です。



さらに、ドキュメントが作成者のグループによって作成された場合、各作成者は自分のデバイスに任せて、資料を提示する独自の方法を実践します。 このため、プレゼンテーション全体が統一されていることがわかりますが、これも間違いと見なす必要があります。 情報がそれぞれの場合に正しく伝えられたとしても、矛盾（構造的、文体的、用語的）は読者を混乱させ、間違った行動に追いやることがあります。



したがって、情報アーキテクチャの対象となる主なタスクの1つは、 出力ドキュメントに必要な繰り返しを提供することですが、著者が作業する資料でそれらを削除することです。

トピック、リンクを含むドキュメントマップ

上記で定式化された原理を簡単な例で示します（表1）。 同時に、情報アーキテクチャの基本要素であるトピック 、 ドキュメントマップ、 リンクの 追加 について も学習します 。 DITAテクノロジーだけでなく、最新のドキュメント自動化テクノロジーにも固有のものです。



表1.情報アーキテクチャーを構築する簡単な例

繰り返し文字	繰り返しによる害	建築ソリューション	反動
異なるドキュメントに同じセクションが含まれている場合があります。	セクションが変更された場合は、必要な情報が失われる危険性があるため、どこでも変更する必要があります。	キットに含まれる各ドキュメントは、目次で結合された小さなセクションで構成されています	著者はセクションを一度修正し、変更はすべての文書に反映されました。 -時間を節約しました。 -除外されたエラー
異なるセクションには、同じテキストフラグメントが含まれる場合があります。たとえば、典型的なセキュリティフレーム	フラグメントが変更された場合は、必要なものが欠落するリスクを伴うすべての場所で変更を行う必要があります	典型的な各フラグメントを個別のファイルに取り出します。 セクションでは、包括的なリンクのみを残しています	著者はフラグメントを一度修正し、変更はすべての文書に反映されました。 -時間を節約しました。 -除外されたエラー

図 図1は、セクションの再利用を示しています。 （再利用という用語は英語の文献でよく使用されますが、ロシア語を「再利用」という言葉で豊かにしたくありません）。



繰り返し使用されるセクションは、一般にトピックと呼ばれます 。 トピックをドキュメントに結合するために使用されるツリー構造（実際には空の目次） は、このドキュメントのマップと呼ばれます。



図1.トピックの再利用







トピックのボリュームはできるだけ小さくする必要があります。



トピックは、明確な境界を持つ1つのトピックに関連する必要があります。 たとえば、トピックは概念の意味を明らかにしたり、手順を説明したり、1組の参照データを含めたりすることができます。



トピックのコンテンツとスタイルは、他のトピックからの相対的な分離を確保するようなものでなければなりません。 トピックは、百科事典の記事や質問に対する適切な回答のように、それ自体で可能な限り明確でなければなりません。 それ以外の場合、作成者は、新しいコンテキストに含まれるたびにこのトピックを手動で修正する必要があります。



図 図2は、より深いレベルの情報アーキテクチャを示しています。 このレベルでは、分解はもはやドキュメントではなくトピックです。



図2.再利用可能なサイドバー

著作権の区分

情報アーキテクチャは、次の条件が満たされている場合にのみ役立ちます。



ユビキタス 。 アーキテクチャについての決定を厳密に遵守し、ケースごとにではなく、体系的にそれらに従う必要があります。 トピックを使用する場合、すべての資料をそれらに分割する必要があります。 標準フレームがある場合は、それらすべてをトピックから取り出して、いくつかのライブラリなどに収集する必要があります。



集合性 。 原則として、多数のドキュメントが多数の作成者によって作成されます。 情報アーキテクチャは、チーム内で効果的な分業を実現する機会を提供します。 例：



-技術的なセキュリティの専門家または弁護士は、サイドバーライブラリをコンパイルできます。そのテキストは慎重に検証されます。

-ホテルの個人的な問題に精通している著者は、彼ら専用のトピックを書くことができます。

-タスク全体を見る編集者は、ドキュメントをマップし、ドキュメントのセット全体のリリースを保証できます。

エンドツーエンドの例

これらの技術の使用を可能にするDITA技術の機能と同様に、情報アーキテクチャを構築するための技術のさらなる検討は、1つの横断的な例に基づいています。



例のプロットは次のとおりです。 電気自動車の技術文書のリリースを手配する必要があると想像してください。 現在、電気自動車には2つのモデルがありますが、その数はさらに増える可能性があります。

すべての名前は架空のものであり、すべての一致はランダムです

この例の各部分の説明は、次の原則に従って行われます。

-出力ドキュメントの要件。

-実装の要件;

-建築ソリューション。

-DITAによる実装。



throughサンプルのソースコードの完全なセットは、私のブログで入手できます。

トピックからの出力ドキュメントのレイアウト

出力要件

各モデルの一連の技術文書には、次の文書が含まれています。

-操作マニュアル;

-広告冊子。



取扱説明書には、モデル全体が記載されています。 広告冊子には、それに関する一般的な情報のみが含まれています。



図3.操作マニュアル（コンテンツ）と広告ブックレット

実装要件

プロジェクト（出力ドキュメントではなく、ソースマテリアル内）での同じテキストの繰り返しを最小限に抑える必要があります。

建築ソリューション

DITAテクノロジーのソリューション標準がここに適用されます。 すでに上で説明されています。 それにもかかわらず、私たちは再びそれについて話し、いくつかの重要な詳細を追加します。



すべての資料は一連のトピックとして提示されます。 トピックを保存するには、ファイルシステムのフォルダー構造を使用します。



各出力ドキュメントには独自のマップがあります。 文書マップには、その構造 、つまり、ネストを考慮したすべてのセクションのシーケンスが含まれています。 トピックをドキュメント構造のセクションにバインドするには、包括的リンクを使用します。 包含リンクは、ドキュメントマップで定義する必要があります。これは、ドキュメント構造のセクションにマップされるトピックを指します（逆の場合も同様です）。



同じカードを使用して異なる出力ドキュメントを生成する技術的能力（たとえば、プロファイリングを使用、以下を参照）にもかかわらず、これは推奨されません。 たとえば、モデルの数が増えてプロジェクトが大きくなると、そのようなアプローチでは、理解できない非常に複雑な構造になる可能性があります。 1つのカード-1つの出力という単純なルールに従うようにしてください。 ここでは、以下に示すように、コストがかかります。



提案されたソリューションは、見た目も一般的です。 プロジェクト資料のさらなる分解中に、重要な決定が表示されます。

DITAの実装

ドキュメントカードの例（この場合はサラゴサモデルの広告ブックレット）を以下に示します。

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> <map id="modSaragosaDatasheet" xml:lang="ru"> <title> «<keyword keyref="prodName"/> <keyword keyref="modName"/>»</title> <!--      --> <mapref href="Common/prodkeys.ditamap"/> <mapref href="Saragosa/modkeys.ditamap"/> <!--     --> <topicref href="Common/topics/overview.dita"/> <topicref href="Common/topics/generalView.dita"/> <topicref href="Common/topics/techParams.dita"/> </map>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

リモートマップとキーリンクの使用については、記事の以下のセクションで説明します。



出力ドキュメントを生成するために、DITA Open Toolkitパッケージは、その構成に含まれるDITA2PDF2プラグインと組み合わせて使用​​されます。DITA2PDF2プラグインは、PDF形式の出力ドキュメントを生成します。



広告ブックレットは非標準のデザインであるため、いわゆるカスタマイズが用意されています。 これは、DITA2PDF2プラグインの標準動作を変更するXSLTスタイルのコレクションです。 このカスタマイズは、横断的な例の一部です。

サンプルテキストをライブラリに入れる

出力要件

想像上のタスクの条件に応じて、電気自動車を使用するための特定のシナリオを説明する各手順は、（必ずしも最初からではなく）典型的なボックスから開始する必要があります。 このボックスには、ドライバーの安全性に関する注記と、安全性セクションへのリンクが含まれています（図4）。



電気自動車の保守に関する特定のシナリオを説明する各手順は、典型的なタイインでも開始する必要がありますが、わずかに異なります。 プロジェクトの後半では、他の典型的な提携が必要になる場合があります。



図4.典型的なフレームの使用

実装要件

すべてのドキュメンテーションキットは、標準フレームのテキストの変更に対して耐性がなければなりません。 標準ボックスのテキストに変更が加えられた場合（たとえば、文学的な改訂が行われたり、新しい規制および技術文書の要件が考慮されたりする場合）、それらはすべての操作マニュアルに等しく反映される必要があります。

建築ソリューション

サンプルテキストライブラリを作成します。 DITA形式の単一ファイルになります。 このファイルには、典型的なテキストのすべての断片が保存されます。 典型的なテキストのライブラリの維持を著者の1人に任せます。著者は、技術的安全性に関する規制の枠組みに特に精通しています。

DITAの実装

サンプルテキストライブラリのフレームビューの例を以下に示します。 典型的なフレームを識別するために、@ id属性が使用されます。 その値は、少なくともライブラリファイル内で一意である必要があります。

 <note id="noteSafety" type="important"> <p> —       .       «».</p> </note> <note id="noteSafetyMnt" type="important"> <p> —      .       «».</p> </note>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

トピックから典型的なフレームへのリンクを含める例を以下に示します。 @conref属性は、典型的なフレームを示すために使用されます。

 <note conref="../../Common/topics/_snippets.dita#commonText/noteSafety"/>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

テキストのパラメーター化

出力要件

トピックのテキストでは、たとえば会社名、製品ラインの名前、特定のモデルの名前など、比較的短い文字列値を見つけることができます（図5）。 ソフトウェアのドキュメントでは、このような値は多くの場合、ソフトウェア製品のバージョン番号、ハードウェアプラットフォームの名前、オペレーティングシステムのバージョン、顧客の名前などになります。



図5.テキストのパラメーター化とコンテキストへの適応







そのような行がすべてのドキュメントで同じテキストに表示される場合、何らかの方法でそれらを削除し、すべての出力ドキュメントに共通のトピックを作成する誘惑があります。 たとえば、製品の名前の代わりに、会社の直接名、単語developerまたはcompanyなどの代わりに、 製品の周辺機器名を使用できます。



アイデアは良いですが、常に機能するとは限りません。



まず、マーケティング上の考慮事項が役割を果たしますが、ドキュメント内のどこかで、元の名前を少なくとも一度明示的に指定する必要があります。



第二に、短い行は必ずしも名前ではありません。 読者がドキュメントの他の部分を探すのではなく、ここで参照することを好むいくつかの重要なパラメータ、技術的制限、ネットワークアドレス、ポート番号またはその他のデータの値を指定できます。



したがって、文字列値を完全に取り除くことは不可能です。 2つのテキストが1ダースまたは2文字だけ異なるという理由だけで2つのテキストを異なるものとみなし、それらを別々のトピックに配置するのは残念です。

実装要件

トピック全体のテキストがすべてのモデルで同じ場合、プロジェクトにはこのトピックの単一のコピーが必要です。 出力ドキュメントを生成する際に、時々、またはモデルごとに変化する可能性のある値は、そのようなトピックに自動的に組み込まれるべきです。

建築ソリューション

すべてのモデルで同じ値ですが、時々変わる可能性のある値（会社、製品ライン全体）には、 名前が割り当てられ、 共通のリモートカードに設定されます 。 共通の拡張カードは、プロジェクト全体の単一のコピーに存在します。 プロジェクトの各ドキュメントのカードに一般的なポータブルカードを含めます。



モデルごとに異なる値（モデルの名前など）には名前が割り当てられ、モデルの外部マップに設定されます。 外部モデルマップは、各モデルの単一のコピーに存在します。 モデルのポータブルマップを、このモデルに関連する各ドキュメントのマップに含めます。



DITAテクノロジーでは、名前付きの値はキーと呼ばれます 。



トピックのテキストでは、値自体ではなく、キー名への参照を使用します。 出力ドキュメントを生成するとき、キー名への各リンクは、リモートカードで指定されたこのキーの現在の値に自動的に置き換えられます（図6）。



図6.キーとリモートマップを使用したトピックのテキストのパラメーター化

DITAの実装

リモートモデルマップのキー定義の例を以下に示します。 一般的なリモートカードは、同じ構文を使用してキーを決定します。

 <keydef keys="modName"> <topicmeta> <keywords> <!--   --> <keyword></keyword> </keywords> </topicmeta> </keydef>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ドキュメントカードから外部カードへのリンクを含める例を以下に示します。

 <!--       --> <mapref href="Common/prodkeys.ditamap"/> <!--       --> <mapref href="Saragosa/modkeys.ditamap"/>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

トピックのテキスト内のキー名へのリンクの例を以下に示します。 出力ドキュメントを生成するとき、製品ラインの名前とモデルの名前がテキストに挿入されます。 キー名へのリンクは、キーワード要素によって表されます。 キー名は@keyref属性で指定されます。

 <p props="manual">   «<keyword keyref="prodName"/> <keyword keyref="modName"/>»   .</p>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

一般的なテキストをコンテキストに適合させる

出力要件

トピックのテキストには、文字列値だけでなく、より複雑な構造も表示できます。 したがって、図 5文字列値に加えて、別の図と表が示されています。 電気自動車の特定のモデルに関連していますが、すべてのモデルに共通するトピックに組み込まれています。

実装要件

トピックのテキストが一般的にすべてのモデルで同じである場合、それは一般的なものでなければなりません。 言い換えれば、このトピックのコピーがプロジェクト内に1つ存在し、必要に応じてすべてのドキュメントのマップにそのトピックへの包括的なリンクが含まれている必要があります。



出力ドキュメントを生成する際に、時々、またはモデルごとに変化する可能性のあるフラグメントは、共通のトピックに自動的に組み込まれるべきです。

建築ソリューション

キーとパラメーター化の助けを借りてこの問題を解決することは不可能です。なぜなら、図と表は文字列値に縮小されないからです。 それらを提示するには、完全なXMLマークアップが必要です。 このようなフラグメントの一般的なテキストへの挿入は、 間接的な包括的リンクを使用して行われます。



一般的なトピックに組み込まれているXMLマークアップのフラグメントは、ワイルドカードと呼ばれます。

特定のモデルに関連するすべてのワイルドカードフラグメントを1つのファイルに収集します。 典型的なテキストライブラリとの類推により、このファイルをモデルライブラリと呼びます。 はい、これは典型的なテキストのライブラリであり、プロジェクト全体ではなく特定のモデルにのみ関連しています。



モデルライブラリを示すために、リモートモデルマップに特別なキーを定義します。 このキーの値は、モデルライブラリへのパスになります。



一般的なトピックから、モデルライブラリ内のこのキーの名前とこのワイルドカードフラグメントの一意の識別子から、目的のワイルドカードフラグメントへの包含リンクを形成します（図7）。



図7.一般的なトピックからワイルドカードフラグメントへの間接的な包含リンク

DITAの実装

以下は、このモデルのライブラリファイルを指すモデルのリモートマップでキーが指定される方法の例です。 href属性は、ワイルドカードフラグメントが配置されているファイルを示すために使用されます。

 <keydef keys="modInfo" href="topics/modinfo.dita"/>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

トピックテキストからワイルドカードフラグメントへの間接リンクの例を以下に示します。 画像要素全体は、リンクを含む間接的なものです。 出力ドキュメントを生成するとき、この間接的な包含リンクが指すワイルドカードフラグメントに完全に置き換えられます。 @conkeyref属性は、ワイルドカードフラグメントを示すために使用されます。 その値は、キー名（modInfoの例）と、目的のワイルドカードフラグメントの@ id属性値（imgGeneralViewの例）で構成されます。 @conkeyref属性値の2つの部分は、スラッシュで入力されます。

 <fig> <image conkeyref="modInfo/imgGeneralView"/> </fig>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

テキストフィルタリング

出力要件

ここで、トピックにテキストを追加するのではなく、捨てることを学びます。



トピックには必要なすべての情報が含まれていることがありますが、特定の出力ドキュメントごとに冗長であることがわかりました。 「技術仕様」のトピック（プロジェクトレベルでの一般的なトピックです）では、次の挿入図が技術仕様の表に続きます。



-ブランドのサービスセンターでのみ電気自動車を整備する必要があることの表示（それ以外の場合、会社は宣言されたパラメーターを保証しません）。

-そのような優れた電気機械を開発したエンジニアへの広告賞賛。



最初のボックスは取扱説明書では適切ですが、広告ブックレットでは不利に見えます。 反対に、2番目のボックスは広告ブックレットでのみ必要であり、取扱説明書ではもう必要ありません。 これらの各フレームは、必要な出力ドキュメントでのみ表示する必要があります（図8）。



図8.出力ドキュメントのジャンルによるテキスト







同様に、一般的なトピックには、特定のモデルにのみ関連するテキストの断片が含まれる場合があります（図9）。



図9.製品モデルによって駆動されるテキスト







他の依存関係、たとえば、一部の機密情報をサービスサポートセンターのマニュアルの拡張バージョンに含める必要があることは容易に想像できますが、エンドユーザーに伝えることは実用的ではありません。

実装要件

特定のコンテキストで冗長になる可能性のあるフラグメントがトピックにあまり多く含まれておらず、そのような各コンテキストが出力ドキュメントの少数の正式な機能で記述できる場合、このトピックのテキストにフィルターを適用する必要があります。 このようなフラグメントのみが互いに異なる複数のトピックを作成することは許可されていません。

建築ソリューション

特定の条件が満たされているか満たされていないときにフラグメントを出力ドキュメントに含めるか、出力ドキュメントから除外する必要がある場合、それを条件付きと呼びます 。 各条件付きフラグメントには、ドキュメントに含める条件またはドキュメントから除外する条件を反映したラベルが提供されます。



出力ドキュメントを作成するとき、どの条件が満たされているかを正確に示します。 不適切な条件付きスニペットは、出力から自動的に除外されます。

DITAの実装

条件付きフラグメントを処理するために、DITAテクノロジーは高度なプロファイリングメカニズムを提供します。 これにより、複数の属性に応じて複数の異なる方法で条件付きフラグメントのフィルタリングを同時に整理できます。



DITA仕様は、独自のセマンティックな意味を持たないいくつかの属性を提供します。作成者はプロファイリングに自由に使用でき、特定のプロジェクトで意味のある方法で値を解釈します。



プロファイリング中に条件付きフラグメントを選択するためのルールは非常に柔軟です。 場合によっては、出力ドキュメントにニュートラルフラグメントと明らかに適切な条件付きフラグメントのみを残す方が便利です。 それ以外の場合、明示的に不適切な条件付きフラグメントを出力から除外する方が簡単です。



一般に、このプロファイリングの主なことは混乱しないことです。 小さい（すでに大きすぎる？）記事でメカニズム全体を説明する力がないため、出力ドキュメントに中立で明らかに適切なフラグメントを含める例を示します。



プロファイリングに関してトピックのソーステキストをマークアップする例を以下に示します。 @ props属性は、ドキュメントのジャンルを示すために使用されます。 この属性の有効な値は、DITA仕様では指定されていません。 これらは情報アーキテクチャの開発中に選択され、このプロジェクトのレベルで採用された契約の一部です。

 <note type="important" props="manual"> <p>               . </p> </note> <sectiondiv props="datasheet"> <p>  ,   ,      .</p> </sectiondiv>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

プロファイリングを実行するには、出力ドキュメントを生成する際に、DITA Open Toolkitパッケージのアセンブリスクリプトを、特にDITAVALファイルと呼ばれるものに転送する必要があります。 プロファイリング属性の特定の値を持つ条件付きフラグメントを出力ドキュメントに含める、または出力ドキュメントから除外する手順を含める必要があります。 このようなファイルの例を以下に示します。

 <?xml version="1.0" encoding="UTF-8"?> <val> <!--     "" --> <prop att="product" val="" action="include"/> <prop att="props" val="manual" action="include"/> <!--   – ! --> <prop att="product" val="" action="exclude"/> <prop att="props" val="datasheet" action="exclude"/> </val>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

トピックの入力と標準化

出力要件

技術文書の状態を記述する主な方法論的および文体的原則の1つ：これも同様に説明する必要があります。 たとえば、ユーザーが実行する手順を説明する場合、常に同じ計画に従ってこれを行う必要があります。



ユーザープロシージャを記述するための世界で最も正しい計画がどこかにあるということではありません。 もちろん、そうではなく、実際にはユーザープロシージャはさまざまな方法で記述できます。 ただし、1つのプロジェクトのフレームワーク内で、すべての作成者に共通のユーザープロシージャを記述する計画を確立し、すべての手順を遵守する必要があります。 そうしないと、意見の相違が始まり、ドキュメントの使用が非常に複雑になります。これは、読者が観察する違いが重要であるかランダムであるかを常に疑問に思わせるためです。

実装要件

プロジェクトに参加している異なる著者（またはプロジェクトに長時間参加している1人の著者）は、同じ現象またはアクションを統一的に記述する必要があります。

建築ソリューション

トピックをいくつかの情報タイプに配布することにより分類します。 一般的な場合の情報タイプのセットは、特定のプロジェクトの機能によって決まります。 トピックを3つの基本的な情報タイプに分けて分類することを開始する強力な（そしてDITAにenられている）伝統があります ：



-理論的;

-手続き;

-参照。



さらに分類するには、3つの基本的な情報タイプ（たとえば、ユーザー手順とインストール手順を区別します）をさらに専門化し、根本的に新しい情報を作成します。



各情報タイプについて、 典型的な構造を開発します。 次の機能は、この情報タイプに属するトピックに固有の典型的な構造によって決定される場合があります。



-トピックの内部構造を形成する見出しのセット。

-見出しの順序と入れ子。

-いくつかの見出しの必須入力。

-それらのために設定された典型的なテキストのいくつかのセクションに必須の存在。



新しいトピックを作成する場合、作成者はまず、このプロジェクトで使用可能なリストから情報タイプを選択する必要があります。 トピックを作成した後、作成者は「クリーンシート」ではなく、比較的厳格なテンプレートを受け取ります。これは、トピックを書くときに従う必要があります。

DITAの実装

彼らはしばしば標準とトレーニングの助けを借りてスタイルの統一の問題を解決しようとします。 部分的に彼らは助けます。 しかし、DITA技術は、他の多くの技術とは異なり、技術的に作成者に統一性を強制することができます。 このために、次のオプションが提供されています。



-DITAの基本情報タイプの使用： トピック、概念、タスク、参照、トラブルシューティング 。 各情報タイプは、DTDとスキーマを使用して記述されます。 作成者が多かれ少なかれ最新のXMLエディターでトピックのテキストを入力すると（通常は発生します）、後者は、このトピックの作成時に選択された情報タイプによって提供される構造を彼に課します。

-基本的な情報タイプの専門化、すなわち 組み込みのものに基づいて独自のDTDまたはトピックスキームを作成します。



特殊な情報タイプを使用するには、XMLエディターとDITA Open Toolkitの追加構成が必要になる場合があります。



検討中の横断的な例では、特殊化は使用せず、標準化を使用しています。 «» . , , , .



. ( XML- ), .

 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> <task id="concept_hy5_32sn_qcb" xml:lang="ru"> <title> </title> <taskbody> <prereq> <!--     --> <note conref="../../Common/topics/_snippets.dita#commonText/noteSafety"/> </prereq> <context> <!--  ,     --> <p><b>    :</b></p> </context> <steps> <step> <cmd></cmd> </step> </steps> </taskbody> </task>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

-?

!



, , . , , .



XSLT ( XSLT-) ( runtime-).



, , DITA, . — .



— .



, - . , . ( , , ..) . . , . , - !



, « » , « » , , . , .



( ) , , . , - , .



. . « ». .



-. , , , - .



, DITA — .

おわりに

, . , , . , , .



, , , . DITA ( ) , , « ». - , «» , , , . , .