dify-docs/plugin-dev-en/0412-doc-understanding-the-dimensions.mdx

---
dimensions:
  type:
    primary: reference
    detail: core
  level: intermediate
standard_title: 'Doc understanding the dimensions'
language: en
title: 'Structured Organization and Sorting Specification in Detail'
---

> <b><i><u>dimensions</u></i></b>

## Background and Motivation: Evolving with the Developer Ecosystem

Dify's initial success was largely due to the intuitive usability of its product. For core users (Users/Buyers), the product experience itself was often sufficient guidance; for the small number of early developers who needed deep customization, they usually had the ability to read the source code directly. Therefore, documentation building was not a top priority in the early stages.

However, with the **launch and flourishing development of the Dify Plugin ecosystem**, the situation has changed significantly:

1. Audience Expansion: Our developer community is no longer limited to core contributors who can dive into the source code. A large number of **"Citizen Developers"** or integration developers with some technical background but who may not be familiar with Dify's underlying structure or specific programming paradigms have emerged, requiring clear, progressive guidance to build and contribute plugins.
2. Content Entanglement and Goal Ambiguity: Existing documentation often mixes **help content** for end users (how to use plugins) with **technical content** for developers (how to develop plugins), causing confusion for both audiences and increasing the cost of finding information.
3. Lack of Structure and Navigation Difficulties: Documentation lacks a unified organizational structure and logical sequence, making it difficult for developers (especially newcomers) to find the information they need and form a complete understanding of the plugin development lifecycle. The existing navigation structure struggles to accommodate growing content.
4. Building Developer Relations (DevRel) Foundation: A clear, effective, and well-structured developer documentation system is an indispensable component in building successful developer relationships and a thriving plugin ecosystem. It directly affects developers' experience, willingness to contribute, and success rate.

Based on these challenges, and analysis of excellent industry examples (such as Zapier Developer Platform, Cloudflare Docs)—which all demonstrate clear audience separation, structured content organization, and pathways designed for different skill levels—we recognized the urgent need for a **systematic restructuring** of Dify's developer documentation.

The dimensions **system** was born out of this need. It is not a rigid set of format requirements, but a solution that crystallizes concepts of **structured thinking, audience segmentation, progressive learning**, and other principles through a **metadata-based automation process**. It aims to provide Dify plugin developers with a clear, consistent, and easy-to-navigate technical knowledge base.

## Core Principle: Metadata as Normative Data Source

The foundation of this system lies in the following core principles:

-   Metadata-Driven: Metadata defined in the Front Matter of each Markdown document (especially dimensions, standard_title, language) is the **Normative Data Source** describing the document's content properties, target audience, and intended use.
-   Decoupling Content from Presentation: The final presentation of the document—including filename, sorting order on the documentation website, navigation menu structure—**must be dynamically generated by automation tools based on this metadata**. Authors should focus on the content itself and the accuracy of its metadata description.
-   Automation for Consistency & Maintainability: Automated processes ensure consistency in structure, naming, and sorting throughout the documentation library. Adjustments to the classification system or sorting logic only require modifications to central configurations and generation scripts for global application, greatly improving maintainability.

This methodology allows content creators (authors) and technical implementers (documentation system maintainers/DevOps) to collaborate effectively, jointly serving the needs of the end developer readers.

## Metadata Specification

Each developer document (Markdown file) must include a YAML Front Matter block defining the following key fields:

```yaml
---
# --- Core Metadata ---

# 'dimensions' for content classification and automatic sorting
dimensions:
    type: # Primary category (Conceptual, Implementation, Operational, Reference) - determines macro order (W)
        primary: <primary_type_value> # Secondary category/detail (Introduction, Basic, Core, Examples...) - determines chapter internal order (X)
        detail: <detail_type_value>
    # Target reader level/content complexity (Beginner, Intermediate, Advanced) - determines micro order (Y) and priority (P)
    level: <level_value>

# 'standard_title' for generating readable filenames and for use on overview pages
standard_title: 'Standard, descriptive title of the document'

# 'language' (ISO 639-1 codes like 'en', 'zh') for internationalization (i18n) and filename suffix
language: <language_code>

# --- Other Optional Metadata ---

# 'summary': Brief summary of document content (optional, may be used for listing pages or SEO)
# 'tags': [list of keywords] (optional, for filtering or relating content)
# ... other fields that may be needed in the future
---
```

```markdown
Type Dimension (Primary)

-   conceptual: Theoretical or explanatory content
-   implementation: Code and development content
-   operational: Content related to running and maintaining the system
-   reference: Reference materials

Type Detail Dimension

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

Level Dimension

-   beginner: For newcomers to the topic
-   intermediate: For users with basic understanding
-   advanced: For advanced users
```

## Deep Analysis of dimensions: Giving Meaning to Content

The dimensions metadata is the core of this system, requiring us to answer three basic questions for each document, thereby giving it a clear **context, scope, and audience positioning**. This classification forms the basis for all subsequent automated structure and sorting.

-   dimensions.type.primary: Defines the "nature" of the content

    -   Core Question: What fundamental type of knowledge does this document belong to? Is it about "what/why" (theory), "how to do" (practice), "how to run/maintain" (operations), or "precise lookup" (reference)?
    -   Function: This dimension establishes the document's **macro category** in the entire knowledge system. We adopt conceptual, implementation, operational, reference—these industry-standard classifications to divide the main areas of developer focus. This classification determines the document's **top-level chapter** or thematic area, and is the first step in building the document's information architecture.

-   dimensions.type.detail: Clarifies the "thematic focus" of the content

    -   Core Question: Within the above macro category, what **specific aspect or subtopic** of that category is this document about? For example, is it an "introductory guide" to a concept, a "standard usage" of an implementation, or the "core API" of reference information?
    -   Function: It provides a **more granular topic division** within the main category. This allows related documents to cluster together, forming logically coherent **sub-chapters** or sections. Choosing the appropriate detail helps users quickly locate specific content points when browsing a particular chapter.

-   dimensions.level: Marks the "complexity and audience" of the content
    -   Core Question: This document on a specific topic is mainly prepared for readers of which **experience level**? Or, what is the **complexity** of its content? Is it beginner, intermediate, or advanced/specialized?
    -   Function: This dimension has a **dual critical role**:
        1. Fine-grained sorting: Within the same specific topic, it allows content to be arranged from easy to difficult, optimizing the learning curve.
        2. Priority determination: It (especially the advanced level) is a key input for the system to distinguish between "core content" and "advanced/deep water content," directly affecting whether content is deprioritized (see Section 5).

Accurately tagging content with these three dimensions is a prerequisite for ensuring that the documentation library is reasonably structured, easy to navigate, and meets the needs of different users.

## Sorting Mechanism: **PWXY** Prefix and Priority Rules

To achieve a consistent and logically clear document presentation order, the system will automatically generate a 4-digit, zero-padded numeric prefix (PWXY) for each document based on its dimensions metadata, using this as part of the filename to implement sorting.

-   P **Priority**: 1st digit. Distinguishes between regular (P=0) and deprioritized/deep water (P=9) content.
-   W **Primary Type Number**: 2nd digit. Reflects the macro order of the primary type.
-   X **Detail Type Number**: 3rd digit. Reflects the order of the detail type within the primary type.
-   Y **Difficulty Level Number**: 4th digit. Reflects the order of the level within the detail type.

Priority (**P=9**) Rule Explanation:

The purpose of marking content as P=9 is to **automatically deprioritize** content that is not essential for beginners and regular use, and that has higher complexity, thereby providing a smoother learning curve and more focused core content flow for the mainstream user group. Conditions that trigger P=9 are:

1. Content defined as advanced: level: advanced.
2. Specific complex details under the implementation category: primary: implementation and detail is high or advanced.

P=9 content can be viewed as the "appendix," "in-depth discussion," or "advanced reference" of the documentation library.

## Filename Generation Strategy

The final deployed filename is generated by automated scripts based on metadata, with its conceptual format being:
`PWXY-[sanitized_standard_title].language.md`

This filename is primarily used for **machine sorting** and internal identification. The document's **human-readable title** is based on the `standard_title` metadata and the H1 title in the document. Automation scripts handle all the details of metadata extraction, PWXY calculation, title sanitization, language suffix, [automatic implementation of GitHub-based edit and feedback buttons](/tools/contributing_in_page.py), and more.

## Audience-Oriented Design Principles: Progressive Disclosure and Path Optimization

This system is permeated by the core principle of "Progressive Disclosure," aiming to optimize information acquisition paths for developers with different backgrounds.

1. Priority Mechanism (P value distinction): This is the main means of implementing progressive disclosure. Systematically separating basic, core, high-frequency use content (P=0) from advanced, complex, specific scenario content (P=9). This ensures that users by default first encounter a relatively streamlined, core-focused knowledge system.
2. Structured Classification (based on type.primary and type.detail): Even within the same priority, content is clearly organized into different categories and topics, providing a predictable "information map" for all users (especially experienced users).

Based on these principles, the system strives to provide optimized experiences for different target audiences:

-   Learners & Newcomers (incl. Citizen Developers): By default viewing the P=0 content sequence, they gain a structured learning path from concepts to basic practices, progressing gradually and reducing initial cognitive load.
-   Experienced Developers & Contributors: Using the clear structure for efficient **random access**, quickly locating specific reference information or implementation details, or directly diving into P=9 advanced content as needed. For them, the documentation library functions more like a technical manual that can be quickly referenced.
-   Automation Tools & Services (e.g., LLMs): Acknowledging their different information consumption patterns compared to humans. Structured metadata **enables us** to generate specially optimized, possibly more flattened data input streams (such as `llms-full.txt`) for them, enhancing their understanding efficiency.

In summary, the dimensions system does not attempt to satisfy everyone with one approach, but rather provides relatively optimal information access and learning paths for different user groups through **structured classification, priority sorting, and metadata-driven automation**.

## System Benefits

-   Clear Structure & Improved Navigation: Based on reliable classification and predictable sorting.
-   Consistent Experience: Automation ensures all documents follow the same pattern.
-   Audience Adaptation: Providing differentiated reading paths through priority distinction.
-   High Maintainability: Adjustments to classification or sorting logic only require modifying central configurations and scripts.
-   Scalability: Easy to add new content types or difficulty levels.
-   Promotes Collaboration: Provides a common foundation for understanding and collaboration standards for authors, reviewers, and system maintainers.

## Creation Process, Roles, and Governance: Addressing Real-World Challenges

Establishing a high-quality documentation library is a process involving multi-party collaboration and facing real-world challenges. The dimensions system aims to be a structured framework and collaboration tool in this process.

### Key Roles in the Collaboration Model

-   Creator / Author:

    -   Core Responsibility: Creating accurate, clear, valuable document content.
    -   Collaboration Point: Learning and trying to understand the dimensions classification system, **attempting** to tag documents with the most appropriate metadata (dimensions, standard_title, language) when submitting. Accurate initial classification helps subsequent processes.

-   Owner / Reviewer:

    -   Core Responsibility: Final quality control of the document's **accuracy, clarity, scope**, and **appropriateness of metadata**. This is the key step in ensuring the quality and structural consistency of the documentation library.
    -   Capability Requirements: Needs to have a profound understanding of the relevant technical field, **while also** understanding the **overall information architecture and audience segmentation logic** behind the dimensions system (which often requires a certain systematic thinking, similar to an architect's perspective).
    -   Collaboration Point: Using dimensions as an objective "ruler" to review content positioning. If metadata is inaccurate or content boundaries are unclear, guide the creator to modify or directly correct the metadata. **The metadata finally merged into the main branch determines how the document is presented**.

-   Operator / DevOps:

    -   Core Responsibility: Maintaining and optimizing the process and tools for documentation automation building, testing, and deployment.
    -   Collaboration Point: Ensuring that automation scripts correctly and efficiently parse metadata and generate final products (sorted files, navigation data, etc.). They focus on the **robustness of the process**, rather than the content details of individual documents.

### Addressing Real-World Documentation Collaboration Challenges

This role division helps us recognize and attempt to mitigate some common documentation dilemmas:

-   "Programmers don't like writing documentation" vs. "Document writers don't understand technology":

    -   The dimensions system **lowers the requirements for creators (programmers)**: The primary task is to write accurate technical content, metadata classification can be "best effort," as reviewers will quality-check.
    -   Meanwhile, it **raises the requirements for reviewers**, acknowledging that high-quality documentation needs profound technical understanding and architectural thinking, and directs this high-level capability toward controlling document structure and metadata.
    -   For potential "dedicated documentation engineers," they can act as creators, or assist reviewers in metadata verification and content refinement, with more flexible roles.

-   High-quality reviewers are scarce and "cost-effectiveness" concerns:

    -   Indeed, reviewers with the required technical depth and architectural thinking are valuable. They might feel that reviewing documentation is "less valuable" compared to core feature development.
    -   The key is to enhance recognition: It must be emphasized that **high-quality, structured documentation has extremely high strategic value for the success of the developer ecosystem, reducing support costs, and increasing product adoption rates**. The dimensions system is a tool that **makes reviewers' high-level thinking explicit and standardized**, and **directly translates it into measurable documentation experience improvements**. Reviewing documentation is no longer "miscellaneous work," but a key link in shaping the developer experience and building a knowledge system.

-   Process Assurance: The dimensions system provides a **collaboration framework**. It encourages creators to think about content positioning, gives reviewers clear evaluation standards and correction authority, and allows operators to independently maintain automation processes. By incorporating metadata checking into the PR process (similar to Code Review), the quality of the final output can be institutionally guaranteed.

## Extensibility and the Role of Code

-   System Extension: The dimensions classification system is not static. As Dify's features evolve, new primary types, detail types, or levels can (and should) be added at appropriate times. This is mainly implemented by updating the central mapping configuration and (if necessary) adjusting generation scripts, demonstrating the system's flexibility.
-   Relationship between Documentation and Code: One of the core goals of developer documentation (especially Reference and advanced Implementation parts) is to serve as an **effective guide** for understanding and using **source code**. It should explain code-level design, usage, constraints, and facilitate developers to **seamlessly dive into the source code**—the ultimate, most precise content—when needed, through means such as linking. Documentation is not a substitute for code, but its **high-quality other side and interpreter**.

{/*
# Frontmatter Metadata Guide

This document helps you quickly define core metadata for Dify developer documentation. Correctly filling out these fields is key to implementing automated document structure and sorting.

## Quick Start

<Tabs>
  <Tab title="Using AI Assistance">
    <Steps>
      <Step title="Prepare document content">
        Complete writing your document content.
      </Step>

      <Step title="Generate metadata with AI">
        Provide your document and the content from [**dimensions system explained**](/plugin-dev-en/0412-doc-understanding-the-dimensions) to your preferred large language model, and request it to generate appropriate Frontmatter.
      </Step>

      <Step title="Manual refinement">
        Based on actual circumstances and the detailed explanations below, make necessary adjustments and optimizations to the generated metadata.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual Definition">
    Read the detailed instructions below and define appropriate metadata fields based on the characteristics of your document content.
  </Tab>
</Tabs>

## Required Frontmatter Fields

Please add the following YAML Frontmatter at the beginning of each Markdown document:

```yaml
---
# --- Core System Metadata (affects structure and sorting) ---
dimensions:
  type:
    primary: <see options below>
    detail: <see options below>
  level: <see options below>
standard_title: 'Descriptive title in English, used for filename generation' # e.g., 'Getting Started Dify Plugin'
language: 'en' # or 'zh', 'ja', etc. (ISO 639-2 code)

# --- Page Content Metadata (optional but recommended) ---
title: 'H1 title or page title of the document'
description: 'Brief SEO description of the document content'
# summary: 'More detailed summary (optional)'
# tags: ['keywords'] (optional)
---
```

## Understanding the `dimensions` Field

<Tabs>
  <Tab title="type.primary">
    <CardGroup cols={2}>
      <Card title="conceptual" icon="lightbulb">
        **Concepts, theory** (what/why)
        <br />Focuses on explaining concepts and fundamental theories
      </Card>

      <Card title="implementation" icon="code">
        **Development practices, code** (how to)
        <br />Focuses on providing implementation steps and code examples
      </Card>

      <Card title="operational" icon="gears">
        **Operations, deployment** (how to run)
        <br />Focuses on system operation and maintenance
      </Card>

      <Card title="reference" icon="book">
        **API, configuration reference** (precise lookup)
        <br />Focuses on technical specifications and reference information
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="type.detail">
    Subdivisions under the `primary` category:

    <AccordionGroup>
      <Accordion title="Subdivisions under conceptual" icon="lightbulb">
        <ul>
          <li><code>introduction</code>: Introductory content</li>
          <li><code>principles</code>: Design principles</li>
          <li><code>architecture</code>: Architectural explanation</li>
        </ul>
      </Accordion>

      <Accordion title="Subdivisions under implementation" icon="code">
        <ul>
          <li><code>basic</code>: Basic implementation</li>
          <li><code>standard</code>: Standard implementation</li>
          <li><code>high</code>: Higher-level implementation (may be deprioritized)</li>
          <li><code>advanced</code>: Advanced implementation (may be deprioritized)</li>
        </ul>
      </Accordion>

      <Accordion title="Subdivisions under operational" icon="gears">
        <ul>
          <li><code>setup</code>: Environment setup</li>
          <li><code>deployment</code>: Deployment operations</li>
          <li><code>maintenance</code>: Maintenance management</li>
        </ul>
      </Accordion>

      <Accordion title="Subdivisions under reference" icon="book">
        <ul>
          <li><code>core</code>: Core reference</li>
          <li><code>configuration</code>: Configuration reference</li>
          <li><code>examples</code>: Example reference</li>
        </ul>
      </Accordion>
    </AccordionGroup>

    <Note>
      For more options, please refer to the [dimensions system explained](/plugin-dev-en/0412-doc-understanding-the-dimensions) document
    </Note>
  </Tab>

  <Tab title="level">
    <CardGroup cols={3}>
      <Card title="beginner" icon="seedling">
        **Newcomer**
        <br />Content suitable for beginners
      </Card>

      <Card title="intermediate" icon="tree">
        **Regular user**
        <br />Content for users with some background knowledge
      </Card>

      <Card title="advanced" icon="mountain">
        **Advanced user**
        <br />In-depth content for professional users (typically deprioritized in sorting)
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## Other Important Fields

<ResponseField name="standard_title" type="string" required>
  Use **English** to clearly describe the core content of the document. The system will use this to generate part of the filename (e.g., `Getting Started Dify Plugin`).
</ResponseField>

<ResponseField name="language" type="string" required>
  ISO 639-2 two-letter language code (such as `en`, `zh`, `ja`).
</ResponseField>

<ResponseField name="title" type="string" recommended>
  The main title of the document displayed on the page, typically in the localized language.
</ResponseField>

<ResponseField name="description" type="string" recommended>
  A brief SEO description for search engines and previews.
</ResponseField>

## Complete Examples

<CodeGroup>
  ```yaml Introductory Document Example
  ---
  dimensions:
    type:
      primary: conceptual
      detail: introduction
    level: beginner
  standard_title: 'Getting Started Dify Plugin'
  language: en
  title: 'Welcome to Dify Plugin Development'
  description: 'Introduction to Dify plugin concepts, functionality, and development value, including a brief explanation of plugin types and an overview of developer documentation content.'
  ---
  ```

  ```yaml Tool Development Document Example
  ---
  dimensions:
    type:
      primary: implementation
      detail: standard
    level: intermediate
  standard_title: 'Developing Tool Plugin'
  language: en
  title: 'Developing Tool Plugins'
  description: 'Detailed guidance on creating and configuring Dify tool plugins, including practical guides on API calls, data processing, and user interface integration.'
  ---
  ```

  ```yaml Reference Document Example
  ---
  dimensions:
    type:
      primary: reference
      detail: configuration
    level: intermediate
  standard_title: 'Plugin Manifest Configuration'
  language: en
  title: 'Plugin Configuration Manifest Reference'
  description: 'Comprehensive explanation of the parameters, format requirements, and use cases for the plugin configuration file (manifest.json).'
  ---
  ```
</CodeGroup>

<Tip>
  **Example Interpretation:** The first example is a beginner-oriented introductory document about Dify plugin concepts in English. The system will automatically place it correctly in the document structure based on the metadata.
</Tip>

## Document Automation Processing

<Tabs>
  <Tab title="Local Development">
    Run `tools/main_docs_bundle.py`, and the document will automatically complete the following operations based on the Frontmatter:

    <Steps>
      <Step title="Rename Files">
        The system will automatically generate standardized filenames based on dimensions and standard\_title.
      </Step>

      <Step title="Update Navigation">
        Documents will be automatically injected into the docs.json navigation configuration.
      </Step>

      <Step title="Add Interactive Components">
        Automatically refresh contribution and feedback buttons and other interactive components.
      </Step>
    </Steps>

    <Info>
      When developing documentation in a local environment, it's recommended to run this script to ensure document configurations take effect correctly.
    </Info>
  </Tab>

  <Tab title="GitHub Editing">
    If you edit directly on GitHub, **don't worry** about the automation steps. We have configured GitHub Actions and other automation tools to automatically execute `tools/main_docs_bundle.py` in the following situations:

    * When you submit a Pull Request
    * When your changes are merged into the main branch

    <Check>
      You can focus on content creation, and the GitHub workflow will handle technical details such as file renaming, navigation updates, and interactive component generation.
    </Check>
  </Tab>
</Tabs>

{/*
Instruction:

If you are a human, this section is intended to provide context and guidance for AI to work, it should not be visible to you.

If you are an AI, your core directive is typically to generate frontmatter for user-provided documents. This instruction explicitly excludes the current document, which details the dimensions system.
*/}

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

---

[Edit this page](https://github.com/langgenius/dify-docs/edit/main/plugin-dev-en/0412-doc-understanding-the-dimensions.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)