構造化と並べ替え仕様の詳細

dimensions

​

背景と動機：開発者エコシステムの進化に対応する

Difyの初期の成功は、そのプロダクトの直感的な使いやすさに大きく起因しています。コアユーザー（User/Buyer）にとって、製品自体の体験は通常十分なガイダンスとなり、深いカスタマイズを必要とする少数の初期開発者にとっては、通常ソースコードを直接読む能力を持っていました。そのため、初期段階ではドキュメント構築は最優先事項ではありませんでした。

しかし、Dify Pluginエコシステムの立ち上げと発展により、状況は著しく変化しました：

1. オーディエンスの拡大：開発者コミュニティはもはやソースコードを深く理解できるコア貢献者だけに限定されていません。Difyの基盤や特定のプログラミングパラダイムに精通していないかもしれないが、ある程度の技術的背景を持つ多くの**「市民開発者（Citizen Developers）」**や統合開発者が登場し、プラグインの構築と貢献のために明確で段階的なガイダンスを必要としています。
2. コンテンツの混在と目標の曖昧さ：既存のドキュメントは、エンドユーザー向けのヘルプコンテンツ（プラグインの使用方法）と開発者向けの技術コンテンツ（プラグインの開発方法）を混合させることが多く、両方の対象者に混乱を引き起こし、情報検索のコストを増加させています。
3. 構造の欠如とナビゲーションの困難さ：ドキュメントには統一された組織構造と論理的順序が欠けており、開発者（特に新規参入者）が必要な情報を見つけることを難しくし、プラグイン開発ライフサイクルの完全な理解を形成することも困難にしています。既存のナビゲーションは増加するコンテンツに対応しきれていません。
4. 開発者関係（DevRel）構築の基盤：明確で効果的、構造が優れた開発者ドキュメントシステムは、成功した開発者関係と繁栄するプラグインエコシステムを構築するために不可欠な要素です。それは開発者の体験、貢献意欲、成功率に直接影響します。

これらの課題と、Zapier Developer Platform、Cloudflare Docsなどの業界の優れた例（いずれも明確なオーディエンス分離、構造化されたコンテンツ組織、異なるスキルレベル向けのパス設計を示しています）の分析に基づいて、私たちはDifyの開発者ドキュメントのシステム的な再構築の緊急性を認識しました。

dimensionsシステムはこの必要性から生まれました。これは硬直した形式要件のセットではなく、上記の問題を解決するために構造化思考、オーディエンスセグメンテーション、段階的学習などの概念をメタデータベースの自動化プロセスを通じて結晶化させたソリューションです。これはDifyプラグイン開発者に明確で一貫性があり、ナビゲーションしやすい技術知識ベースを提供することを目的としています。

​

核心原則：メタデータを規範的データソースとして

このシステムの基盤は、以下の核心原則にあります：

• メタデータ駆動（Metadata-Driven）：各Markdownドキュメントのフロントマターで定義されたメタデータ（特にdimensions、standard_title、language）は、そのドキュメントのコンテンツ属性、対象オーディエンス、意図された用途を記述する**規範的データソース（Normative Data Source）**です。
• コンテンツとプレゼンテーションの分離（Decoupling Content from Presentation）：ドキュメントの最終的な表示形式—ファイル名、ドキュメントサイト上での並び順、ナビゲーションメニュー構造—はすべて自動化ツールによってこれらのメタデータに基づいて動的に生成される必要があります。著者はコンテンツ自体とそのメタデータ記述の正確性に集中すべきです。
• 一貫性と保守性のための自動化（Automation for Consistency & Maintainability）：自動化プロセスはドキュメントライブラリ全体の構造、命名、並び順の一貫性を確保します。分類システムや並べ替えロジックの調整は、中央設定と生成スクリプトを修正するだけでグローバルに適用でき、保守性を大幅に向上させます。

この方法論により、コンテンツ作成者（著者）と技術実装者（ドキュメントシステム保守者/DevOps）が効果的に協力し、最終的な開発者読者のニーズに共同で対応することができます。

​

メタデータ仕様

各開発者ドキュメント（Markdownファイル）には、以下の重要なフィールドを定義するYAML Front Matterブロックが含まれていなければなりません：

---
# --- コアメタデータ ---

# 'dimensions' はコンテンツ分類と自動ソート用
dimensions:
    type: # 主要カテゴリ (Conceptual, Implementation, Operational, Reference) - マクロ順序を決定 (W)
        primary: <primary_type_value> # 副次カテゴリ/詳細 (Introduction, Basic, Core, Examples...) - 章内順序を決定 (X)
        detail: <detail_type_value>
    # 対象読者レベル/コンテンツ複雑度 (Beginner, Intermediate, Advanced) - ミクロ順序 (Y) と優先度 (P) を決定
    level: <level_value>

# 'standard_title' は読みやすいファイル名の生成と概要ページでの使用のため
standard_title: 'ドキュメントの標準的な説明的タイトル'

# 'language' (ISO 639-1コード例：'en', 'zh', 'ja') は国際化(i18n)とファイル名サフィックスのため
language: <language_code>

# --- その他のオプションメタデータ ---

# 'summary': ドキュメント内容の簡潔な要約 (オプション、リストページやSEO用に使用される可能性あり)
# 'tags': [キーワードリスト] (オプション、フィルタリングや関連コンテンツ用)
# ... 将来必要になる可能性のある他のフィールド
---

タイプディメンション（プライマリ）

-   conceptual: 理論的または説明的コンテンツ
-   implementation: コードと開発コンテンツ
-   operational: システムの実行と維持に関するコンテンツ
-   reference: 参考資料

タイプ詳細ディメンション

-   conceptual向け: introduction, principles, architecture
-   implementation向け: basic, standard, high, advanced
-   operational向け: setup, deployment, maintenance
-   reference向け: core, configuration, examples

レベルディメンション

-   beginner: トピックの初心者向け
-   intermediate: 基本的な理解を持つユーザー向け
-   advanced: 上級ユーザー向け

​

dimensionsの深層分析：コンテンツに意味を与える

dimensionsメタデータはこのシステムの核心であり、各ドキュメントに対して3つの基本的な質問に答えることを要求し、それによって明確なコンテキスト、スコープ、オーディエンスの位置づけを与えます。この分類は、後続のすべての自動化構造と並べ替えの基礎となります。

• dimensions.type.primary：コンテンツの「性質」を定義

  • 核心的質問: このドキュメントは根本的にどのタイプの知識に属するか？それは「何か/なぜか」（理論）、「どうやって」（実践）、「どう実行/維持するか」（運用）、または「正確な検索」（参考）に関するものか？
  • 機能: このディメンションはドキュメントが知識体系全体の中でマクロカテゴリを確立します。開発者が焦点を当てる主要な領域を区分けするために、業界で共通のconceptual、implementation、operational、referenceという分類を採用しています。この分類はドキュメントが属するトップレベルの章またはテーマ領域を決定し、ドキュメントの情報アーキテクチャを構築する第一歩です。

• dimensions.type.detail：コンテンツの「テーマフォーカス」を明確にする

  • 核心的質問: 上記のマクロカテゴリ内で、このドキュメントは具体的にそのカテゴリのどの特定の側面やサブトピックに関するものか？例えば、あるコンセプトの「入門ガイド」、ある実装の「標準的な使用法」、または参照情報の「コアAPI」か？
  • 機能: 主要カテゴリ内でより細かいトピック区分を提供します。これにより関連ドキュメントがまとまり、論理的に一貫したサブチャプターまたは段落を形成します。適切な詳細を選択することで、特定の章を閲覧する際にユーザーが具体的なコンテンツポイントを素早く特定するのに役立ちます。

• dimensions.level：コンテンツの「複雑さと対象者」をマーク

  • 核心的質問: この特定トピックに関するドキュメントは、主にどの経験レベルの読者向けか？あるいは、そのコンテンツの複雑さはどうか？入門（beginner）、一般（intermediate）、それとも深い/専門的（advanced）か？
  • 機能: このディメンションには二重の重要な役割があります：
    1. 細粒度の並べ替え: 同一の具体的なトピック内で、コンテンツを易しいものから難しいものへと順序付け、学習曲線を最適化します。
    2. 優先度判定: 特に高度（advanced）レベルは、システムが「コアコンテンツ」と「高度/深水域コンテンツ」を区別するための重要な入力であり、コンテンツが後回しにされるかどうかに直接影響します（セクション5参照）。

これら3つのディメンションでコンテンツに正確にタグ付けすることは、ドキュメントライブラリが合理的に構造化され、ナビゲーションが容易で、異なるユーザーのニーズを満たすための前提条件です。

​

ソートメカニズム：PWXYプレフィックスと優先度ルール

一貫性があり論理的に明確なドキュメント表示順序を実現するために、システムはdimensionsメタデータに基づいて各ドキュメントに4桁のゼロパディングされた数字プレフィックス（PWXY）を自動生成し、これをファイル名の一部として使用して並べ替えを実装します。

• P 優先度（Priority）: 1桁目。通常（P=0）と後回し/深水域（P=9）コンテンツを区別します。
• W 主要タイプ番号（Primary Type）: 2桁目。primaryタイプのマクロ順序を反映します。
• X 詳細タイプ番号（Detail Type）: 3桁目。主要タイプ内でのdetailタイプの順序を反映します。
• Y 難易度レベル番号（Level）: 4桁目。詳細タイプ内でのlevelの順序を反映します。

優先度（P=9）ルールの説明:

コンテンツをP=9としてマークする目的は、初心者と通常使用に不可欠ではない、複雑さの高いコンテンツを自動的に後回しにすることで、主流のユーザーグループにより滑らかな学習曲線とより集中したコアコンテンツフローを提供することです。P=9をトリガーする条件は：

1. 高度と定義されたコンテンツ: level: advanced。
2. 実装カテゴリの下の特定の複雑な詳細: primary: implementation かつ detail が high または advanced。

P=9のコンテンツはドキュメントライブラリの「付録」、「詳細な議論」、または「高度な参考資料」とみなすことができます。

​

ファイル名生成戦略

最終的にデプロイされるファイル名は、メタデータに基づいて自動化スクリプトによって生成され、その概念形式は次のとおりです： PWXY-[sanitized_standard_title].language.md

このファイル名は主に機械ソートと内部識別のために使用されます。ドキュメントの人間が読めるタイトルは、standard_titleメタデータとドキュメント内のH1タイトルに基づいています。自動化スクリプトはメタデータ抽出、PWXY計算、タイトルのサニタイズ、言語サフィックス、GitHubベースの編集とフィードバックボタンの自動実装などすべての詳細を処理します。

​

オーディエンス指向の設計原則：段階的開示とパス最適化

このシステムには「段階的開示（Progressive Disclosure）」の核心原則が浸透しており、異なる背景を持つ開発者の情報取得パスを最適化することを目指しています。

1. 優先度メカニズム（P値区別）：これは段階的開示を実装する主要な手段です。基本的、コア的、高頻度使用コンテンツ（P=0）と高度、複雑、特定シナリオのコンテンツ（P=9）を体系的に分離します。これにより、ユーザーはデフォルトでまず比較的簡素化され、コアに焦点を当てた知識体系に出会うことが保証されます。
2. 構造化分類（type.primaryとtype.detailに基づく）：同じ優先度内でも、コンテンツは異なるカテゴリとトピックに明確に組織化され、すべてのユーザー（特に経験豊富なユーザー）に予測可能な「情報マップ」を提供します。

これらの原則に基づき、システムは異なる対象オーディエンスに最適化された体験を提供するよう努めています：

• 学習者と新規参入者（Citizen Developersを含む）：デフォルトでP=0のコンテンツシーケンスを閲覧し、概念から基本的な実践へと構造化された学習パスを獲得し、段階的に進み、初期の認知負荷を軽減します。
• 経験豊富な開発者と貢献者：明確な構造を利用して効率的なランダムアクセスを行い、特定の参照情報や実装の詳細を素早く特定するか、必要に応じて直接P=9の高度なコンテンツに飛び込みます。彼らにとって、ドキュメントライブラリはより素早く参照できる技術マニュアルのように機能します。
• 自動化ツールとサービス（例：LLM）：人間とは異なる情報消費パターンを認識します。構造化されたメタデータにより、特別に最適化された、おそらくよりフラット化されたデータ入力ストリーム（llms-full.txtなど）を生成することが可能になり、理解効率を高めます。

要約すると、dimensionsシステムは1つのアプローチですべての人を満足させようとするのではなく、構造化分類、優先度ソート、メタデータ駆動の自動化を通じて、異なるユーザーグループに比較的最適な情報アクセスと学習パスを提供します。

​

システムの利点

• 明確な構造とナビゲーションの改善：信頼性の高い分類と予測可能な並べ替えに基づいています。
• 一貫した体験：自動化によりすべてのドキュメントが同じパターンに従うことを保証します。
• オーディエンス適応：優先度区別を通じて、差別化された読書パスを提供します。
• 高い保守性：分類や並べ替えロジックの調整は、中央の設定とスクリプトを修正するだけで行えます。
• 拡張性：新しいコンテンツタイプや難易度レベルの追加が容易です。
• 協力を促進：著者、レビュアー、システム保守者に共通の理解基盤と協力基準を提供します。

​

創作プロセス、役割、ガバナンス：現実世界の課題への対応

高品質のドキュメントライブラリの確立は、複数の当事者の協力を伴い、現実世界の課題に直面するプロセスです。dimensionsシステムはこのプロセスにおいて構造化されたフレームワークと協力ツールとなることを目指しています。

​

協力モデルにおける主要な役割

• クリエイター/著者：

  • 核心的責任：正確で明確、価値のあるドキュメントコンテンツの作成。
  • 協力のポイント：dimensionsの分類システムを学び理解しようとし、提出時にドキュメントに最も適切なメタデータ（dimensions、standard_title、language）を試みること。正確な初期分類はその後のプロセスに役立ちます。

• オーナー/レビュアー：

  • 核心的責任：ドキュメントの正確性、明確さ、範囲およびメタデータの適切さの最終的な品質管理。これはドキュメントライブラリの品質と構造的一貫性を確保するための重要なステップです。
  • 能力要件：関連する技術分野の深い理解を持ち、同時にdimensionsシステムの背後にある全体的な情報アーキテクチャとオーディエンスセグメンテーションロジックを理解する必要があります（これはしばしば、アーキテクトの視点に似た、一定のシステム的思考を必要とします）。
  • 協力のポイント：dimensionsを客観的な「ものさし」としてコンテンツ位置付けをレビューする。メタデータが不正確またはコンテンツ境界が曖昧な場合は、クリエイターに修正を指導するか、メタデータを直接修正する。最終的にメインブランチにマージされるメタデータがドキュメントの表示方法を決定します。

• オペレーター/DevOps：

  • 核心的責任：ドキュメント自動化ビルド、テスト、デプロイのプロセスとツールの維持と最適化。
  • 協力のポイント：自動化スクリプトが正確かつ効率的にメタデータを解析し、最終製品（ソートされたファイル、ナビゲーションデータなど）を生成することを確保する。彼らは個々のドキュメントのコンテンツ詳細よりも、プロセスの堅牢性に焦点を当てています。

​

実際のドキュメント協力の課題への対応

この役割分担は、いくつかの一般的なドキュメントのジレンマを認識し、軽減する助けとなります：

• 「プログラマーはドキュメントを書くのが好きではない」vs「ドキュメントを書く人は技術を理解していない」：

  • dimensionsシステムはクリエイター（プログラマー）への要求を下げる：第一の任務は正確な技術的内容を書くことであり、メタデータ分類は「最善を尽くす」ことができます。なぜならレビュアーが品質チェックを行うからです。
  • 同時に、それはレビュアーへの要求を高め、高品質のドキュメントには深い技術的理解とアーキテクチャ的思考が必要であることを認め、この高レベルの能力をドキュメント構造とメタデータの制御に向けます。
  • 潜在的な「専任ドキュメントエンジニア」については、彼らはクリエイターとして行動するか、またはレビュアーのメタデータ検証とコンテンツの洗練を支援することができ、役割はより柔軟です。

• 高品質レビュアーは希少で「費用対効果」の懸念：

  • 確かに、必要な技術的深さとアーキテクチャ的思考を持つレビュアーは貴重です。彼らはコア機能開発と比較してドキュメントのレビューは「価値が低い」と感じるかもしれません。
  • 鍵となるのは認識を高めることです：高品質で構造化されたドキュメントは、開発者エコシステムの成功、サポートコストの削減、製品採用率の向上のために非常に高い戦略的価値を持っていることを強調する必要があります。dimensionsシステムは、レビュアーの高レベルの思考を明示的、標準化し、直接測定可能なドキュメント体験の向上に変換するツールです。ドキュメントのレビューはもはや「雑用」ではなく、開発者体験を形成し、知識体系を構築する重要なリンクです。

• プロセス保証：dimensionsシステムは協力フレームワークを提供します。それはクリエイターにコンテンツの位置付けを考えるよう促し、レビュアーに明確な評価基準と修正権限を与え、オペレーターが自動化プロセスを独立して維持できるようにします。メタデータチェックをPRプロセスに組み込むことで（Code Reviewと同様）、最終出力の品質を制度的に保証することができます。

​

拡張性とコードの役割

• システム拡張：dimensions分類システムは静的ではありません。Difyの機能が進化するにつれて、新しいprimaryタイプ、detailタイプ、またはlevelを適切なタイミングで追加することができます（そしてすべきです）。これは主に中央マッピング設定を更新し、（必要に応じて）生成スクリプトを調整することで実装され、システムの柔軟性を示しています。
• ドキュメントとコードの関係：開発者ドキュメント（特にReferenceと高度なImplementationの部分）の核心的な目標の一つは、ソースコードを理解し使用するための効果的なガイドとして機能することです。それはコードレベルの設計、使用法、制約を説明し、リンクなどの手段を通じて、開発者が必要なときに最終的で最も正確なコンテンツであるソースコードにシームレスに深入りすることを促進すべきです。ドキュメントはコードの代替品ではなく、その高品質な別の側面と解釈者です。