Structured Organization and Sorting Specification in Detail

dimensions

​

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:

---
# --- 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
---

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, 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.