Structured Organization and Sorting Specification in Detail

dimensions

​

Background and Motivation: Evolving with the Developer Ecosystem

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.

​

Core Principle: Metadata as Normative Data Source

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

​

Metadata Specification

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

• 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).

​

Sorting Mechanism: PWXY Prefix and Priority Rules

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

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

​

Filename Generation Strategy

​

Audience-Oriented Design Principles: Progressive Disclosure and Path Optimization

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

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

​

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

​

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

• “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.