mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-03-27 13:28:32 +07:00
feat: contributor guides
This commit is contained in:
Alter-xyz
24
docs.json
24
docs.json
@@ -592,6 +592,14 @@
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "About This Documentation",
|
||||
"pages": [
|
||||
"plugin_dev_en/0411-doc-contribution-guide.en",
|
||||
"plugin_dev_en/0412-doc-writing-dimensions-guide.en",
|
||||
"plugin_dev_en/0412-doc-understanding-the-dimensions.en"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -1221,6 +1229,14 @@
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "关于本文档",
|
||||
"pages": [
|
||||
"plugin_dev_zh/0411-doc-contribution-guide.zh",
|
||||
"plugin_dev_zh/0412-doc-writing-dimensions-guide.zh",
|
||||
"plugin_dev_zh/0412-doc-understanding-the-dimensions.zh"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -1813,6 +1829,14 @@
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "ドキュメントについて",
|
||||
"pages": [
|
||||
"plugin_dev_ja/0411-doc-contribution-guide.ja",
|
||||
"plugin_dev_ja/0412-doc-writing-dimensions-guide.ja",
|
||||
"plugin_dev_ja/0412-doc-understanding-the-dimensions.ja"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
135
plugin_dev_en/0411-doc-contribution-guide.en.mdx
Normal file
135
plugin_dev_en/0411-doc-contribution-guide.en.mdx
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: core
|
||||
level: beginner
|
||||
standard_title: 'Doc Contribution Guide'
|
||||
language: en
|
||||
title: 'Contribution Guide'
|
||||
summary: 'Learn how to contribute to Dify developer documentation, including steps and guidelines for updating existing documentation and creating new documentation, to collectively build high-quality documentation resources.'
|
||||
---
|
||||
|
||||
Welcome to the collaborative construction of Dify documentation! This guide aims to explain the contribution process and specifications for Dify developer documentation, encouraging and assisting community members to collectively improve documentation quality.
|
||||
|
||||
## Updating Existing Documentation
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Recommended Method">
|
||||
At the bottom of the documentation page you wish to modify, click the <Icon icon="pen-to-square" /> **Edit this page** button. This will directly link to the corresponding source file on GitHub.
|
||||
|
||||
</Tab>
|
||||
<Tab title="Via URL Location">
|
||||
Dify documentation URLs have a clear correspondence with their relative paths in the GitHub repository, which can be referenced by contributors familiar with the structure:
|
||||
|
||||
| URL (example) | GitHub Repository Relative Path (example) |
|
||||
| :--- | :--- |
|
||||
| `https://docs.dify.ai/plugin_dev_en/0111-getting-started-dify-plugin.en` | `plugin_dev_en/0111-getting-started-dify-plugin.en.mdx` |
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
<Note>
|
||||
When editing, please focus on the accuracy and clarity of the content. The Frontmatter metadata at the beginning of the file and specific scripts or included content at the end are typically managed and maintained by core contributors or through automated processes.
|
||||
</Note>
|
||||
|
||||
<Check>
|
||||
If you find issues with the documentation, you can also report them to us using the **Submit an issue** button on the page. Accurate issue reporting is an important contribution for both the community and the project.
|
||||
</Check>
|
||||
|
||||
## Creating New Documentation
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the File">
|
||||
Create a new `.mdx` file in the appropriate language directory (e.g., `plugin_dev_en`).
|
||||
|
||||
You can initially name the file as you wish (e.g., `my-new-feature.mdx`), but the filename must be sufficiently descriptive. The system will later generate a standardized filename based on the document's metadata.
|
||||
</Step>
|
||||
|
||||
<Step title="Write the Content">
|
||||
<Accordion title="Markdown Syntax Guidelines">
|
||||
Please follow standard **Markdown** syntax. In MDX files, use JSX-style comments: `{/* This is an MDX comment */}`, rather than HTML-style `<!-- comment -->`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Mintlify Components">
|
||||
You can appropriately use components provided by Mintlify to optimize content structure and presentation:
|
||||
|
||||
```jsx
|
||||
<Note>
|
||||
This is an important note.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
This is a warning message.
|
||||
</Warning>
|
||||
|
||||
<Card title="Related Resources" icon="book">
|
||||
For more information, please refer to related resources...
|
||||
</Card>
|
||||
```
|
||||
|
||||
For more components, please refer to the [Mintlify components documentation](https://mintlify.com/docs).
|
||||
</Accordion>
|
||||
</Step>
|
||||
|
||||
<Step title="Add Frontmatter (Metadata)">
|
||||
Each document needs to define Frontmatter metadata:
|
||||
|
||||
* Correctly configured Frontmatter is key to ensuring that the documentation can be accurately indexed, sorted, and correctly displayed and navigated on the documentation website.
|
||||
* **Your primary task is to contribute high-quality, accurate documentation content.**
|
||||
* If you are familiar with Dify's [Documentation Frontmatter Metadata Guide](/plugin_dev_en/0412-doc-writing-dimensions-guide.en), we welcome you to include Frontmatter when submitting.
|
||||
* **If you're unsure how to fill in the Frontmatter, or wish to focus on content creation, that's perfectly fine.** You can submit a Pull Request without Frontmatter or with only partial metadata. The community and project core contributors will assist you with subsequent additions, reviews, and optimizations.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Check>
|
||||
**Your content contribution is crucial.** Even if you don't provide complete Frontmatter, your Pull Request is still welcome. Ensuring the documentation ultimately has standardized metadata and successful integration is a collaborative effort between the community and the core team.
|
||||
</Check>
|
||||
|
||||
## Submitting Your Contribution
|
||||
|
||||
After completing the editing or creation of new documentation, please submit a Pull Request to the main repository through GitHub. Community members and project maintainers will review your contribution.
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Can I contribute to documentation if I don't have a programming background?">
|
||||
Absolutely! Documentation contributions don't require programming skills. If you have some understanding of Dify, you can help improve the clarity and accuracy of existing documentation, or add more user-friendly explanations and examples.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How can I ensure my contribution is accepted?">
|
||||
Ensure your content is clear, accurate, and follows our formatting guidelines. Check for spelling and grammar before submission. If you're uncertain, you can discuss your ideas in the community before submitting.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Can I contribute in languages other than English?">
|
||||
Yes! We welcome multilingual documentation contributions. Please ensure your files are placed in the corresponding language directory and correctly labeled with the language code in the Frontmatter.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
---
|
||||
|
||||
Thank you for contributing to the Dify community and documentation!
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
It will be automatically generated by the script.
|
||||
*/}
|
||||
|
||||
<CardGroup cols="2">
|
||||
<Card
|
||||
title="Edit this page"
|
||||
icon="pen-to-square"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/plugin_dev_en/0411-doc-contribution-guide.en.mdx"
|
||||
>
|
||||
Help improve our documentation by contributing directly
|
||||
</Card>
|
||||
<Card
|
||||
title="Report an issue"
|
||||
icon="github"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=Documentation%20Issue%3A%20doc-contribution-guide&body=%23%23%20Issue%20Description%0A%3C%21--%20Please%20briefly%20describe%20the%20issue%20you%20found%20--%3E%0A%0A%23%23%20Page%20Link%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fplugin_dev_en%2F0411-doc-contribution-guide.en.mdx%0A%0A%23%23%20Suggested%20Changes%0A%3C%21--%20If%20you%20have%20specific%20suggestions%20for%20changes%2C%20please%20describe%20them%20here%20--%3E%0A%0A%3C%21--%20Thank%20you%20for%20helping%20improve%20our%20documentation%21%20--%3E"
|
||||
>
|
||||
Found an error or have suggestions? Let us know
|
||||
</Card>
|
||||
</CardGroup>
|
||||
227
plugin_dev_en/0412-doc-understanding-the-dimensions.en.mdx
Normal file
227
plugin_dev_en/0412-doc-understanding-the-dimensions.en.mdx
Normal file
@@ -0,0 +1,227 @@
|
||||
---
|
||||
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**.
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
It will be automatically generated by the script.
|
||||
*/}
|
||||
|
||||
<CardGroup cols="2">
|
||||
<Card
|
||||
title="Edit this page"
|
||||
icon="pen-to-square"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/plugin_dev_en/0412-doc-understanding-the-dimensions.en.mdx"
|
||||
>
|
||||
Help improve our documentation by contributing directly
|
||||
</Card>
|
||||
<Card
|
||||
title="Report an issue"
|
||||
icon="github"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=Documentation%20Issue%3A%20doc-understanding-the-dimensions&body=%23%23%20Issue%20Description%0A%3C%21--%20Please%20briefly%20describe%20the%20issue%20you%20found%20--%3E%0A%0A%23%23%20Page%20Link%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fplugin_dev_en%2F0412-doc-understanding-the-dimensions.en.mdx%0A%0A%23%23%20Suggested%20Changes%0A%3C%21--%20If%20you%20have%20specific%20suggestions%20for%20changes%2C%20please%20describe%20them%20here%20--%3E%0A%0A%3C%21--%20Thank%20you%20for%20helping%20improve%20our%20documentation%21%20--%3E"
|
||||
>
|
||||
Found an error or have suggestions? Let us know
|
||||
</Card>
|
||||
</CardGroup>
|
||||
273
plugin_dev_en/0412-doc-writing-dimensions-guide.en.mdx
Normal file
273
plugin_dev_en/0412-doc-writing-dimensions-guide.en.mdx
Normal file
@@ -0,0 +1,273 @@
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: core
|
||||
level: intermediate
|
||||
standard_title: 'Doc writing Dimensions guide'
|
||||
language: en
|
||||
title: 'Frontmatter Metadata Guide'
|
||||
summary: 'Learn how to use the metadata structure of the Dify documentation system to correctly define document properties and enable automated organization and sorting.'
|
||||
---
|
||||
|
||||
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.en) 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.en) 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>
|
||||
|
||||
<Card title="Want to learn more?" icon="book-open" href="/plugin_dev_en/0412-doc-understanding-the-dimensions.en">
|
||||
If you're interested in the design philosophy of the Dimensions system, the complete details of the sorting mechanism, or roles and governance, please read the full Dimensions system detailed explanation document.
|
||||
</Card>
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
It will be automatically generated by the script.
|
||||
*/}
|
||||
|
||||
<CardGroup cols="2">
|
||||
<Card
|
||||
title="Edit this page"
|
||||
icon="pen-to-square"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/plugin_dev_en/0412-doc-writing-dimensions-guide.en.mdx"
|
||||
>
|
||||
Help improve our documentation by contributing directly
|
||||
</Card>
|
||||
<Card
|
||||
title="Report an issue"
|
||||
icon="github"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=Documentation%20Issue%3A%20doc-writing-dimensions-guide&body=%23%23%20Issue%20Description%0A%3C%21--%20Please%20briefly%20describe%20the%20issue%20you%20found%20--%3E%0A%0A%23%23%20Page%20Link%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fplugin_dev_en%2F0412-doc-writing-dimensions-guide.en.mdx%0A%0A%23%23%20Suggested%20Changes%0A%3C%21--%20If%20you%20have%20specific%20suggestions%20for%20changes%2C%20please%20describe%20them%20here%20--%3E%0A%0A%3C%21--%20Thank%20you%20for%20helping%20improve%20our%20documentation%21%20--%3E"
|
||||
>
|
||||
Found an error or have suggestions? Let us know
|
||||
</Card>
|
||||
</CardGroup>
|
||||
5
plugin_dev_en/README.md
Normal file
5
plugin_dev_en/README.md
Normal file
@@ -0,0 +1,5 @@
|
||||
# Dify Plugin Developer Documentation
|
||||
|
||||
This guide aims to help developers quickly get started with Dify plugin development by providing necessary documentation and resource links.
|
||||
|
||||
Contribution Guide: [Dify Docs](https://docs.dify.ai/plugin_dev_en/0411-doc-contribution-guide.en)
|
||||
135
plugin_dev_ja/0411-doc-contribution-guide.ja.mdx
Normal file
135
plugin_dev_ja/0411-doc-contribution-guide.ja.mdx
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: core
|
||||
level: beginner
|
||||
standard_title: 'Doc Contribution Guide'
|
||||
language: ja
|
||||
title: '貢献ガイド'
|
||||
summary: 'Dify開発者ドキュメントへの貢献方法を学び、既存ドキュメントの更新や新規ドキュメントの作成ステップとガイドラインを理解し、高品質なドキュメントリソースを共同で構築しましょう。'
|
||||
---
|
||||
|
||||
Difyドキュメントの共同構築へようこそ！このガイドでは、Dify開発者ドキュメントへの貢献プロセスと仕様を説明し、コミュニティメンバーがドキュメントの品質を共同で向上させることを奨励・支援します。
|
||||
|
||||
## 既存ドキュメントの更新
|
||||
|
||||
<Tabs>
|
||||
<Tab title="推奨方法">
|
||||
修正したいドキュメントページの下部にある <Icon icon="pen-to-square" /> **このページを編集する** ボタンをクリックしてください。これにより、GitHubの対応するソースファイルに直接リンクします。
|
||||
|
||||
</Tab>
|
||||
<Tab title="URL経由での特定">
|
||||
DifyドキュメントのURLは、GitHubリポジトリ内の相対パスと明確に対応しています。構造に慣れた貢献者は以下を参考にできます：
|
||||
|
||||
| URL (例) | GitHubリポジトリの相対パス (例) |
|
||||
| :--- | :--- |
|
||||
| `https://docs.dify.ai/plugin_dev_ja/0111-getting-started-dify-plugin.ja` | `plugin_dev_ja/0111-getting-started-dify-plugin.ja.mdx` |
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
<Note>
|
||||
編集する際は、コンテンツの正確性と明確さに焦点を当ててください。ファイルの先頭にあるFrontmatterメタデータや、末尾の特定のスクリプトや含まれるコンテンツは、通常、コア貢献者または自動化プロセスによって管理・維持されています。
|
||||
</Note>
|
||||
|
||||
<Check>
|
||||
ドキュメントに問題を見つけた場合は、ページにある **問題を報告する** ボタンを使用して報告することもできます。正確な問題報告は、コミュニティとプロジェクトの両方にとって重要な貢献です。
|
||||
</Check>
|
||||
|
||||
## 新規ドキュメントの作成
|
||||
|
||||
<Steps>
|
||||
<Step title="ファイルの作成">
|
||||
適切な言語ディレクトリ（例：`plugin_dev_ja`）に新しい`.mdx`ファイルを作成します。
|
||||
|
||||
最初はファイル名を自由に決めることができます（例：`my-new-feature.mdx`）が、ファイル名は十分に説明的である必要があります。システムは後で、ドキュメントのメタデータに基づいて標準化されたファイル名を生成します。
|
||||
</Step>
|
||||
|
||||
<Step title="コンテンツの作成">
|
||||
<Accordion title="Markdown構文ガイドライン">
|
||||
標準の **Markdown** 構文に従ってください。MDXファイルでは、HTML形式の `<!-- comment -->` ではなく、JSX形式のコメント：`{/* これはMDXコメントです */}` を使用してください。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Mintlifyコンポーネント">
|
||||
Mintlifyが提供するコンポーネントを適切に使用して、コンテンツの構造と表示を最適化できます：
|
||||
|
||||
```jsx
|
||||
<Note>
|
||||
これは重要な注意事項です。
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
これは警告メッセージです。
|
||||
</Warning>
|
||||
|
||||
<Card title="関連リソース" icon="book">
|
||||
詳細については、関連リソースを参照してください...
|
||||
</Card>
|
||||
```
|
||||
|
||||
その他のコンポーネントについては、[Mintlifyコンポーネントドキュメント](https://mintlify.com/docs)を参照してください。
|
||||
</Accordion>
|
||||
</Step>
|
||||
|
||||
<Step title="Frontmatter（メタデータ）の追加">
|
||||
各ドキュメントにはFrontmatterメタデータを定義する必要があります：
|
||||
|
||||
* 正しく設定されたFrontmatterは、ドキュメントが正確にインデックス化され、適切に並べ替えられ、ドキュメントウェブサイト上で正しく表示・ナビゲートされるようにするための鍵です。
|
||||
* **あなたの主な任務は、高品質で正確なドキュメントコンテンツを提供することです。**
|
||||
* Difyの[ドキュメントFrontmatterメタデータガイド](/plugin_dev_ja/0412-doc-writing-dimensions-guide.ja)に精通している場合は、提出時にFrontmatterを含めることを歓迎します。
|
||||
* **Frontmatterの記入方法がわからない場合や、コンテンツ作成に集中したい場合でも問題ありません。** Frontmatterなし、または部分的なメタデータのみでPull Requestを提出できます。コミュニティやプロジェクトのコア貢献者が、その後の追加、レビュー、最適化を支援します。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Check>
|
||||
**あなたのコンテンツ貢献は非常に重要です。** 完全なFrontmatterを提供できなくても、あなたのPull Requestは歓迎されます。ドキュメントが最終的に標準化されたメタデータを持ち、正常に統合されるようにすることは、コミュニティとコアチームの協力的な取り組みです。
|
||||
</Check>
|
||||
|
||||
## 貢献の提出
|
||||
|
||||
ドキュメントの編集や新規作成が完了したら、GitHubを通じてメインリポジトリにPull Requestを送信してください。コミュニティメンバーとプロジェクトのメンテナーがあなたの貢献をレビューします。
|
||||
|
||||
## よくある質問
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="プログラミングのバックグラウンドがなくてもドキュメントに貢献できますか？">
|
||||
もちろんです！ドキュメントへの貢献にプログラミングスキルは必要ありません。Difyについて理解があれば、既存ドキュメントの明確さと正確さを向上させたり、よりユーザーフレンドリーな説明や例を追加したりすることができます。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="私の貢献が受け入れられるためにはどうすればよいですか？">
|
||||
コンテンツが明確で正確であり、フォーマットガイドラインに従っていることを確認してください。提出前にスペルと文法をチェックしてください。不確かな場合は、提出前にコミュニティでアイデアを議論することができます。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="日本語以外の言語で貢献できますか？">
|
||||
はい！多言語ドキュメントの貢献を歓迎します。ファイルが対応する言語ディレクトリに配置され、Frontmatterで言語コードが正しくラベル付けされていることを確認してください。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
---
|
||||
|
||||
Difyコミュニティとドキュメントへの貢献に感謝します！
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
It will be automatically generated by the script.
|
||||
*/}
|
||||
|
||||
<CardGroup cols="2">
|
||||
<Card
|
||||
title="このページを編集する"
|
||||
icon="pen-to-square"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/plugin_dev_ja/0411-doc-contribution-guide.ja.mdx"
|
||||
>
|
||||
直接貢献することでドキュメントの改善にご協力ください
|
||||
</Card>
|
||||
<Card
|
||||
title="問題を報告する"
|
||||
icon="github"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=ドキュメントの問題%3A%20doc-contribution-guide&body=%23%23%20問題の説明%0A%3C%21--%20発見した問題について簡単に説明してください%20--%3E%0A%0A%23%23%20ページリンク%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fplugin_dev_ja%2F0411-doc-contribution-guide.ja.mdx%0A%0A%23%23%20提案される変更%0A%3C%21--%20特定の変更案がある場合は、ここで説明してください%20--%3E%0A%0A%3C%21--%20ドキュメントの品質向上にご協力いただきありがとうございます！%20--%3E"
|
||||
>
|
||||
エラーを見つけたり提案がありますか？お知らせください
|
||||
</Card>
|
||||
</CardGroup>
|
||||
227
plugin_dev_ja/0412-doc-understanding-the-dimensions.ja.mdx
Normal file
227
plugin_dev_ja/0412-doc-understanding-the-dimensions.ja.mdx
Normal file
@@ -0,0 +1,227 @@
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: core
|
||||
level: intermediate
|
||||
standard_title: 'Doc understanding the dimensions'
|
||||
language: ja
|
||||
title: '構造化と並べ替え仕様の詳細'
|
||||
---
|
||||
|
||||
> <b><i><u>dimensions</u></i></b>
|
||||
|
||||
## 背景と動機：開発者エコシステムの進化に対応する
|
||||
|
||||
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ブロックが含まれていなければなりません：
|
||||
|
||||
```yaml
|
||||
---
|
||||
# --- コアメタデータ ---
|
||||
|
||||
# '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': [キーワードリスト] (オプション、フィルタリングや関連コンテンツ用)
|
||||
# ... 将来必要になる可能性のある他のフィールド
|
||||
---
|
||||
```
|
||||
|
||||
```markdown
|
||||
タイプディメンション（プライマリ）
|
||||
|
||||
- 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ベースの編集とフィードバックボタンの自動実装](/tools/contributing_in_page.py)などすべての詳細を処理します。
|
||||
|
||||
## オーディエンス指向の設計原則：段階的開示とパス最適化
|
||||
|
||||
このシステムには「段階的開示（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の部分）の核心的な目標の一つは、**ソースコード**を理解し使用するための**効果的なガイド**として機能することです。それはコードレベルの設計、使用法、制約を説明し、リンクなどの手段を通じて、開発者が必要なときに最終的で最も正確なコンテンツである**ソースコードにシームレスに深入り**することを促進すべきです。ドキュメントはコードの代替品ではなく、その**高品質な別の側面と解釈者**です。
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
It will be automatically generated by the script.
|
||||
*/}
|
||||
|
||||
<CardGroup cols="2">
|
||||
<Card
|
||||
title="このページを編集する"
|
||||
icon="pen-to-square"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/plugin_dev_ja/0412-doc-understanding-the-dimensions.ja.mdx"
|
||||
>
|
||||
直接貢献することでドキュメントの改善にご協力ください
|
||||
</Card>
|
||||
<Card
|
||||
title="問題を報告する"
|
||||
icon="github"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=ドキュメントの問題%3A%20doc-understanding-the-dimensions&body=%23%23%20問題の説明%0A%3C%21--%20発見した問題について簡単に説明してください%20--%3E%0A%0A%23%23%20ページリンク%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fplugin_dev_ja%2F0412-doc-understanding-the-dimensions.ja.mdx%0A%0A%23%23%20提案される変更%0A%3C%21--%20特定の変更案がある場合は、ここで説明してください%20--%3E%0A%0A%3C%21--%20ドキュメントの品質向上にご協力いただきありがとうございます！%20--%3E"
|
||||
>
|
||||
エラーを見つけたり提案がありますか？お知らせください
|
||||
</Card>
|
||||
</CardGroup>
|
||||
273
plugin_dev_ja/0412-doc-writing-dimensions-guide.ja.mdx
Normal file
273
plugin_dev_ja/0412-doc-writing-dimensions-guide.ja.mdx
Normal file
@@ -0,0 +1,273 @@
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: core
|
||||
level: intermediate
|
||||
standard_title: 'Doc writing Dimensions guide'
|
||||
language: ja
|
||||
title: 'Frontmatterメタデータガイド'
|
||||
summary: 'Difyドキュメントシステムのメタデータ構造を使用して、ドキュメントプロパティを正しく定義し、自動組織化と並べ替えを可能にする方法を学びます。'
|
||||
---
|
||||
|
||||
このドキュメントは、Dify開発者ドキュメントのコアメタデータを迅速に定義するのに役立ちます。これらのフィールドを正確に記入することは、ドキュメントの自動化された構造と並べ替えを実装するための鍵です。
|
||||
|
||||
## クイックスタート
|
||||
|
||||
<Tabs>
|
||||
<Tab title="AI支援の利用">
|
||||
<Steps>
|
||||
<Step title="ドキュメントコンテンツの準備">
|
||||
ドキュメントコンテンツの作成を完了します。
|
||||
</Step>
|
||||
<Step title="AIでメタデータを生成">
|
||||
あなたのドキュメントと[**dimensionsシステムの説明**](/plugin_dev_ja/0412-doc-understanding-the-dimensions.ja)の内容を、お好みの大規模言語モデルに提供し、適切なFrontmatterの生成を依頼します。
|
||||
</Step>
|
||||
<Step title="手動での調整">
|
||||
実際の状況と以下の詳細な説明に基づいて、生成されたメタデータに必要な調整と最適化を行います。
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
<Tab title="手動定義">
|
||||
以下の詳細な説明を読み、ドキュメントコンテンツの特性に基づいて適切なメタデータフィールドを定義します。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 必須Frontmatterフィールド
|
||||
|
||||
各Markdownドキュメントの先頭に以下のYAML Frontmatterを追加してください：
|
||||
|
||||
```yaml
|
||||
---
|
||||
# --- コアシステムメタデータ（構造と並べ替えに影響）---
|
||||
dimensions:
|
||||
type:
|
||||
primary: <以下のオプションを参照>
|
||||
detail: <以下のオプションを参照>
|
||||
level: <以下のオプションを参照>
|
||||
standard_title: '英語による説明的なタイトル、ファイル名生成に使用' # 例：'Getting Started Dify Plugin'
|
||||
language: 'ja' # または 'en', 'zh'など（ISO 639-2コード）
|
||||
|
||||
# --- ページコンテンツメタデータ（オプションだが推奨）---
|
||||
title: 'ドキュメントのH1タイトルまたはページタイトル'
|
||||
description: 'ドキュメントコンテンツの簡潔なSEO説明'
|
||||
# summary: 'より詳細な要約（オプション）'
|
||||
# tags: ['キーワード']（オプション）
|
||||
---
|
||||
```
|
||||
|
||||
## `dimensions`フィールドの理解
|
||||
|
||||
<Tabs>
|
||||
<Tab title="type.primary">
|
||||
<CardGroup cols={2}>
|
||||
<Card title="conceptual" icon="lightbulb">
|
||||
**概念、理論**（何/なぜ）
|
||||
<br />概念と基本理論の説明に焦点を当てる
|
||||
</Card>
|
||||
<Card title="implementation" icon="code">
|
||||
**開発プラクティス、コード**（どのように）
|
||||
<br />実装手順とコード例の提供に焦点を当てる
|
||||
</Card>
|
||||
<Card title="operational" icon="gears">
|
||||
**運用、デプロイメント**（どのように実行する）
|
||||
<br />システム運用と保守に焦点を当てる
|
||||
</Card>
|
||||
<Card title="reference" icon="book">
|
||||
**API、設定リファレンス**（正確な検索）
|
||||
<br />技術仕様とリファレンス情報の提供に焦点を当てる
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</Tab>
|
||||
|
||||
<Tab title="type.detail">
|
||||
`primary`カテゴリの下位区分：
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="conceptualの下位区分" icon="lightbulb">
|
||||
<ul>
|
||||
<li><code>introduction</code>: 導入コンテンツ</li>
|
||||
<li><code>principles</code>: 設計原則</li>
|
||||
<li><code>architecture</code>: アーキテクチャの説明</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="implementationの下位区分" icon="code">
|
||||
<ul>
|
||||
<li><code>basic</code>: 基本的な実装</li>
|
||||
<li><code>standard</code>: 標準的な実装</li>
|
||||
<li><code>high</code>: 高度な実装（優先度が下がる可能性あり）</li>
|
||||
<li><code>advanced</code>: 高度な実装（優先度が下がる可能性あり）</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="operationalの下位区分" icon="gears">
|
||||
<ul>
|
||||
<li><code>setup</code>: 環境設定</li>
|
||||
<li><code>deployment</code>: デプロイメント操作</li>
|
||||
<li><code>maintenance</code>: メンテナンス管理</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="referenceの下位区分" icon="book">
|
||||
<ul>
|
||||
<li><code>core</code>: コアリファレンス</li>
|
||||
<li><code>configuration</code>: 設定リファレンス</li>
|
||||
<li><code>examples</code>: 例示リファレンス</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
より多くのオプションについては、[dimensionsシステムの説明](/plugin_dev_ja/0412-doc-understanding-the-dimensions.ja)ドキュメントを参照してください
|
||||
</Note>
|
||||
</Tab>
|
||||
|
||||
<Tab title="level">
|
||||
<CardGroup cols={3}>
|
||||
<Card title="beginner" icon="seedling">
|
||||
**初心者**
|
||||
<br />初心者向けのコンテンツ
|
||||
</Card>
|
||||
<Card title="intermediate" icon="tree">
|
||||
**一般ユーザー**
|
||||
<br />ある程度の背景知識を持つユーザー向けのコンテンツ
|
||||
</Card>
|
||||
<Card title="advanced" icon="mountain">
|
||||
**上級ユーザー**
|
||||
<br />専門ユーザー向けの詳細なコンテンツ（通常、並べ替えで優先度が下がる）
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## その他の重要なフィールド
|
||||
|
||||
<ResponseField name="standard_title" type="string" required>
|
||||
**英語**を使用して、ドキュメントのコアコンテンツを明確に説明します。システムはこれを使用してファイル名の一部を生成します（例：`Getting Started Dify Plugin`）。
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="language" type="string" required>
|
||||
ISO 639-2の2文字言語コード（例：`en`、`zh`、`ja`）。
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="title" type="string" recommended>
|
||||
ページに表示されるドキュメントのメインタイトル、通常はローカライズされた言語で記述されます。
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="description" type="string" recommended>
|
||||
検索エンジンとプレビュー用の簡潔なSEO説明。
|
||||
</ResponseField>
|
||||
|
||||
## 完全な例
|
||||
|
||||
<CodeGroup>
|
||||
```yaml 導入ドキュメントの例
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: conceptual
|
||||
detail: introduction
|
||||
level: beginner
|
||||
standard_title: 'Getting Started Dify Plugin'
|
||||
language: ja
|
||||
title: 'Difyプラグイン開発へようこそ'
|
||||
description: 'Difyプラグインの概念、機能、開発価値の紹介。プラグインタイプの簡単な説明と開発者ドキュメントの内容の概要を含みます。'
|
||||
---
|
||||
```
|
||||
|
||||
```yaml ツール開発ドキュメントの例
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: implementation
|
||||
detail: standard
|
||||
level: intermediate
|
||||
standard_title: 'Developing Tool Plugin'
|
||||
language: ja
|
||||
title: 'ツールプラグインの開発'
|
||||
description: 'Difyツールプラグインの作成と設定に関する詳細なガイダンス。APIコール、データ処理、ユーザーインターフェイス統合に関する実践ガイドを含みます。'
|
||||
---
|
||||
```
|
||||
|
||||
```yaml リファレンスドキュメントの例
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: configuration
|
||||
level: intermediate
|
||||
standard_title: 'Plugin Manifest Configuration'
|
||||
language: ja
|
||||
title: 'プラグイン設定マニフェストリファレンス'
|
||||
description: 'プラグイン設定ファイル（manifest.json）のパラメータ、フォーマット要件、ユースケースに関する包括的な説明。'
|
||||
---
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Tip>
|
||||
**例の解釈：** 最初の例は、初心者向けのDifyプラグインの概念に関する導入ドキュメントで、言語は日本語です。システムはメタデータに基づいて、ドキュメント構造内に自動的に正しく配置します。
|
||||
</Tip>
|
||||
|
||||
## ドキュメント自動化処理
|
||||
|
||||
<Tabs>
|
||||
<Tab title="ローカル開発">
|
||||
`tools/main_docs_bundle.py`を実行すると、ドキュメントはFrontmatterに基づいて以下の操作を自動的に完了します：
|
||||
|
||||
<Steps>
|
||||
<Step title="ファイル名の変更">
|
||||
システムはdimensionsとstandard_titleに基づいて標準化されたファイル名を自動的に生成します。
|
||||
</Step>
|
||||
<Step title="ナビゲーションの更新">
|
||||
ドキュメントはdocs.jsonナビゲーション設定に自動的に挿入されます。
|
||||
</Step>
|
||||
<Step title="インタラクティブコンポーネントの追加">
|
||||
貢献とフィードバックボタンなどのインタラクティブコンポーネントを自動的に更新します。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Info>
|
||||
ローカル環境でドキュメントを開発する場合、ドキュメント設定が正しく反映されるようにこのスクリプトを実行することをお勧めします。
|
||||
</Info>
|
||||
</Tab>
|
||||
|
||||
<Tab title="GitHub編集">
|
||||
|
||||
GitHubで直接編集する場合は、自動化ステップについて**心配しないでください**。私たちは、次の状況で`tools/main_docs_bundle.py`を自動的に実行するようにGitHub Actionなどの自動化ツールを設定しています：
|
||||
|
||||
- Pull Requestを提出するとき
|
||||
- 変更がメインブランチにマージされるとき
|
||||
|
||||
<Check>
|
||||
コンテンツ作成に集中できます。GitHubワークフローがファイル名の変更、ナビゲーションの更新、インタラクティブコンポーネントの生成などの技術的な詳細を処理します。
|
||||
</Check>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Card title="もっと詳しく知りたいですか？" icon="book-open" href="/plugin_dev_ja/0412-doc-understanding-the-dimensions.ja">
|
||||
Dimensionsシステムの設計哲学、並べ替えメカニズムの完全な詳細、または役割とガバナンスに興味がある場合は、Dimensionsシステムの詳細な説明ドキュメントをお読みください。
|
||||
</Card>
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
It will be automatically generated by the script.
|
||||
*/}
|
||||
|
||||
<CardGroup cols="2">
|
||||
<Card
|
||||
title="このページを編集する"
|
||||
icon="pen-to-square"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/plugin_dev_ja/0412-doc-writing-dimensions-guide.ja.mdx"
|
||||
>
|
||||
直接貢献することでドキュメントの改善にご協力ください
|
||||
</Card>
|
||||
<Card
|
||||
title="問題を報告する"
|
||||
icon="github"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=ドキュメントの問題%3A%20doc-writing-dimensions-guide&body=%23%23%20問題の説明%0A%3C%21--%20発見した問題について簡単に説明してください%20--%3E%0A%0A%23%23%20ページリンク%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fplugin_dev_ja%2F0412-doc-writing-dimensions-guide.ja.mdx%0A%0A%23%23%20提案される変更%0A%3C%21--%20特定の変更案がある場合は、ここで説明してください%20--%3E%0A%0A%3C%21--%20ドキュメントの品質向上にご協力いただきありがとうございます！%20--%3E"
|
||||
>
|
||||
エラーを見つけたり提案がありますか？お知らせください
|
||||
</Card>
|
||||
</CardGroup>
|
||||
5
plugin_dev_ja/README.md
Normal file
5
plugin_dev_ja/README.md
Normal file
@@ -0,0 +1,5 @@
|
||||
# Dify プラグイン開発者ドキュメント
|
||||
|
||||
本ガイドは、開発者が Dify プラグインの開発を迅速に開始できるよう、必要なドキュメントとリソースリンクを提供することを目的としています。
|
||||
|
||||
貢献ガイド: [Dify Docs](https://docs.dify.ai/plugin_dev_ja/0411-doc-contribution-guide.ja)
|
||||
135
plugin_dev_zh/0411-doc-contribution-guide.zh.mdx
Normal file
135
plugin_dev_zh/0411-doc-contribution-guide.zh.mdx
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: core
|
||||
level: beginner
|
||||
standard_title: 'Doc Contribution Guide'
|
||||
language: zh
|
||||
title: '贡献指南'
|
||||
summary: '了解如何为 Dify 开发者文档贡献内容，包括更新现有文档和创建新文档的步骤与规范，共同建设高质量的文档资源。'
|
||||
---
|
||||
|
||||
欢迎参与 Dify 文档的协同构建！本指南旨在阐述 Dify 开发者文档的贡献流程与规范，鼓励并协助社区成员共同提升文档质量。
|
||||
|
||||
## 更新现有文档
|
||||
|
||||
<Tabs>
|
||||
<Tab title="推荐方式">
|
||||
在您希望修改的文档页面末尾，点击 <Icon icon="pen-to-square" /> **编辑此页面** 按钮。这将直接链接到 GitHub 上对应的源文件。
|
||||
|
||||
</Tab>
|
||||
<Tab title="通过 URL 定位">
|
||||
Dify 文档的 URL 与其在 GitHub 仓库中的相对路径存在明确的对应关系，可供熟悉结构的贡献者参考：
|
||||
|
||||
| 网址 (示例) | GitHub 仓库相对路径 (示例) |
|
||||
| :--- | :--- |
|
||||
| `https://docs.dify.ai/plugin_dev_zh/0111-getting-started-dify-plugin.zh` | `plugin_dev_zh/0111-getting-started-dify-plugin.zh.mdx` |
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
<Note>
|
||||
编辑时，请专注于正文内容的准确性和清晰度。文件头部的 Frontmatter 元数据及末尾的特定脚本或包含内容，通常由核心贡献者或通过自动化流程进行管理和维护。
|
||||
</Note>
|
||||
|
||||
<Check>
|
||||
如发现文档问题，您也可以通过页面上的 **提交问题** 按钮向我们报告。准确的问题反馈对社区和项目而言都是重要的贡献。
|
||||
</Check>
|
||||
|
||||
## 创建新文档
|
||||
|
||||
<Steps>
|
||||
<Step title="创建文件">
|
||||
在相应的语言目录下 (例如 `plugin_dev_zh`) 创建一个新的 `.mdx` 文件。
|
||||
|
||||
初始文件名可自行定义 (例如 `my-new-feature.mdx`)，文件名必须足够长。系统后续会根据文档元数据自动生成规范化的文件名。
|
||||
</Step>
|
||||
|
||||
<Step title="编写内容">
|
||||
<Accordion title="Markdown 语法规范">
|
||||
请遵循标准的 **Markdown** 语法。在 MDX 文件中，注释请使用 JSX 风格：`{/* 这是一个 MDX 注释 */}`，而非 HTML 风格的 `<!-- comment -->`。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Mintlify 组件">
|
||||
可适当运用 Mintlify 提供的组件优化内容结构与呈现：
|
||||
|
||||
```jsx
|
||||
<Note>
|
||||
这是一个重要提示。
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
这是一个警告信息。
|
||||
</Warning>
|
||||
|
||||
<Card title="相关资源" icon="book">
|
||||
更多内容请参考相关资源...
|
||||
</Card>
|
||||
```
|
||||
|
||||
更多组件请参考 [Mintlify 组件文档](https://mintlify.com/docs)。
|
||||
</Accordion>
|
||||
</Step>
|
||||
|
||||
<Step title="添加 Frontmatter (元数据)">
|
||||
每篇文档都需要定义 Frontmatter 元数据：
|
||||
|
||||
* 正确配置的 Frontmatter 是确保文档能够被系统准确索引、排序并在文档网站上正确显示和导航的关键。
|
||||
* **您的首要任务是贡献高质量、准确的文档内容。**
|
||||
* 如果您熟悉 Dify 的 [文档 Frontmatter 元数据指南](/plugin_dev_zh/0412-doc-writing-dimensions-guide.zh)，我们非常欢迎您在提交时包含 Frontmatter。
|
||||
* **如果您不确定如何填写 Frontmatter，或者希望专注于内容创作，完全没有问题。** 您可以提交不包含 Frontmatter 或仅包含部分元数据的 Pull Request。社区和项目核心贡献者会协助您进行后续的添加、审核与优化。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Check>
|
||||
**您的内容贡献至关重要。** 即使您未提供完整的 Frontmatter，您的 Pull Request 依然受欢迎。确保文档最终拥有规范的元数据并成功集成，是社区与核心团队协作完成的工作。
|
||||
</Check>
|
||||
|
||||
## 提交您的贡献
|
||||
|
||||
完成编辑或创建新文档后，请通过 GitHub 向主仓库提交 Pull Request。社区成员和项目维护者将对您的贡献进行审阅。
|
||||
|
||||
## 常见问题解答
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="我没有编程背景，可以贡献文档吗？">
|
||||
当然可以！文档贡献不需要编程技能。如果您对 Dify 有所了解，您可以帮助改进现有文档的清晰度、准确性，或添加更多用户友好的说明和示例。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="如何确保我的贡献被接受？">
|
||||
确保您的内容清晰、准确，并遵循我们的格式指南。在提交前检查拼写和语法。如果不确定，可以在提交前在社区中讨论您的想法。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="我可以用英语以外的语言贡献吗？">
|
||||
可以！我们欢迎多语言文档贡献。请确保您的文件放在对应语言的目录中，并在 Frontmatter 中正确标注语言代码。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
---
|
||||
|
||||
感谢您为 Dify 社区和文档建设贡献力量！
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
It will be automatically generated by the script.
|
||||
*/}
|
||||
|
||||
<CardGroup cols="2">
|
||||
<Card
|
||||
title="编辑此页面"
|
||||
icon="pen-to-square"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/plugin_dev_zh/0411-doc-contribution-guide.zh.mdx"
|
||||
>
|
||||
通过直接提交修改来帮助改进文档内容
|
||||
</Card>
|
||||
<Card
|
||||
title="提交问题"
|
||||
icon="github"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=文档问题%3A%20doc-contribution-guide&body=%23%23%20问题描述%0A%3C%21--%20请简要描述您发现的问题%20--%3E%0A%0A%23%23%20页面链接%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fplugin_dev_zh%2F0411-doc-contribution-guide.zh.mdx%0A%0A%23%23%20建议修改%0A%3C%21--%20如果有具体的修改建议，请在此说明%20--%3E%0A%0A%3C%21--%20感谢您对文档质量的关注！%20--%3E"
|
||||
>
|
||||
发现错误或有改进建议？请提交问题反馈
|
||||
</Card>
|
||||
</CardGroup>
|
||||
227
plugin_dev_zh/0412-doc-understanding-the-dimensions.zh.mdx
Normal file
227
plugin_dev_zh/0412-doc-understanding-the-dimensions.zh.mdx
Normal file
@@ -0,0 +1,227 @@
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: core
|
||||
level: intermediate
|
||||
standard_title: 'Doc understanding the dimensions'
|
||||
language: zh
|
||||
title: '结构化与排序规范详解'
|
||||
---
|
||||
|
||||
> <b><i><u>dimensions</u></i></b>
|
||||
|
||||
## 背景与动机：应对开发者生态的演进
|
||||
|
||||
Dify 最初的成功很大程度上源于其产品的直观易用性。对于核心用户（User/Buyer），产品本身的体验往往足以引导他们；对于少数需要深度定制的早期开发者而言，他们通常具备直接阅读源代码的能力。因此，初期的文档建设并非最高优先级。
|
||||
|
||||
然而，随着 **Dify Plugin 插件生态的上线和蓬勃发展**，情况发生了显著变化：
|
||||
|
||||
1. 受众扩大化： 我们的开发者社区不再局限于能够深入源码的核心贡献者。大量拥有一定技术背景但可能不熟悉 Dify 底层或特定编程范式的**“半专业开发者” (Citizen Developers)** 或集成开发者涌现，他们需要清晰、循序渐进的指导来构建和贡献插件。
|
||||
2. 内容交织与目标模糊： 现有的文档往往将面向最终用户的**帮助内容**（如何使用插件）与面向开发者的**技术内容**（如何开发插件）混合在一起，导致两类受众都感到困惑，增加了信息查找成本。
|
||||
3. 结构缺失与导航困难： 文档缺乏统一的组织结构和逻辑顺序，使得开发者（尤其是新加入者）难以找到所需信息，也无法形成对插件开发生命周期的完整认知。现有导航难以承载日益增长的内容。
|
||||
4. 构建开发者关系 (DevRel) 的基石： 一个清晰、有效、结构优异的开发者文档体系，是构建成功开发者关系、繁荣插件生态不可或缺的一环。它直接影响开发者的体验、贡献意愿和成功率。
|
||||
|
||||
基于以上挑战，以及对业界优秀范例（如 Zapier Developer Platform, Cloudflare Docs）的分析——它们都展现了清晰的受众分离、结构化的内容组织和面向不同技能水平的路径设计——我们认识到对 Dify 的开发者文档进行**系统性重构**的迫切性。
|
||||
|
||||
dimensions**系统**应运而生。它并非一套僵化的格式要求，而是我们为了解决上述问题，将**结构化思维、受众细分、渐进式学习**等理念，通过一套**基于元数据的自动化流程**沉淀下来的解决方案。它旨在为 Dify 插件开发者提供一个清晰、一致且易于导航的技术知识库。
|
||||
|
||||
## 核心原则：元数据作为规范性数据源
|
||||
|
||||
本系统的基石在于以下核心原则：
|
||||
|
||||
- 元数据驱动 (Metadata-Driven): 每篇 Markdown 文档的 Front Matter 中定义的元数据（特别是 dimensions, standard_title, language）是描述该文档内容属性、目标受众和预期用途的**规范性数据源 (Normative Data Source)**。
|
||||
- 内容与表现分离 (Decoupling Content from Presentation): 文档的最终呈现形式——包括文件名、在文档网站上的排序、导航菜单结构——都**必须由自动化工具根据这些元数据动态生成**。作者应专注于内容本身及其元数据描述的准确性。
|
||||
- 自动化保障一致性与可维护性 (Automation for Consistency & Maintainability): 自动化流程确保了整个文档库在结构、命名和排序上的一致性。对分类体系或排序逻辑的调整，只需修改中央配置和生成脚本即可全局应用，极大地提高了可维护性。
|
||||
|
||||
这种方法论让内容创作者（作者）和技术实现者（文档系统维护者/DevOps）能够有效协作，共同服务于最终开发者读者的需求。
|
||||
|
||||
## 元数据规范
|
||||
|
||||
每篇开发者文档（Markdown 文件）必须包含一个 YAML Front Matter 块，定义如下关键字段：
|
||||
|
||||
```yaml
|
||||
---
|
||||
# --- 核心元数据 ---
|
||||
|
||||
# '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') 用于国际化(i18n)和文件名后缀
|
||||
language: <language_code>
|
||||
|
||||
# --- 其他可选元数据 ---
|
||||
|
||||
# 'summary': 文档内容的简短摘要 (可选, 可能用于列表页或 SEO)
|
||||
# 'tags': [关键词列表] (可选, 用于过滤或关联内容)
|
||||
# ... 其他未来可能需要的字段
|
||||
---
|
||||
```
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## dimensions 深度解析：为内容赋予意义
|
||||
|
||||
dimensions 元数据是本系统的核心，它要求我们为每一篇文档回答三个基本问题，从而赋予其明确的**语境、范围和受众定位**。这种分类是后续所有自动化结构和排序的基础。
|
||||
|
||||
- dimensions.type.primary：定义内容的“性质”
|
||||
|
||||
- 核心问题: 这篇文档从根本上属于哪一类知识？它是关于“是什么/为什么”（理论），“如何做”（实践），“如何运行/维护”（运维），还是“精确查找”（参考）？
|
||||
- 作用: 这个维度确立了文档在整个知识体系中的**宏观类别**。我们采用 conceptual, implementation, operational, reference 这几个业界通用的分类，来划分开发者关注的主要领域。这个分类决定了文档所属的**顶层章节**或主题区域，是构建文档信息架构的第一步。
|
||||
|
||||
- dimensions.type.detail：明确内容的“主题焦点”
|
||||
|
||||
- 核心问题: 在上述宏观类别下，这篇文档具体是关于该类别的哪个**特定方面或子主题**？例如，是某个概念的“入门介绍”，还是某个实现的“标准用法”，或是某个参考信息的“核心 API”？
|
||||
- 作用: 它在主类别内部提供了**更精细的主题划分**。这使得相关的文档能够聚集在一起，形成逻辑连贯的**子章节**或段落。选择恰当的 detail 有助于用户在浏览特定章节时快速定位到具体内容点。
|
||||
|
||||
- dimensions.level：标定内容的“复杂度与受众”
|
||||
- 核心问题: 这篇特定主题的文档，主要是为哪个**经验水平的读者**准备的？或者说，其内容的**复杂度**如何？是入门 (beginner)，通用 (intermediate)，还是深入/专门 (advanced)？
|
||||
- 作用: 这个维度具有**双重关键作用**：
|
||||
1. 细粒度排序: 在同一具体主题下，它允许内容按从易到难的顺序排列，优化学习曲线。
|
||||
2. 优先级判定: 它（尤其是 advanced 级别）是系统区分“核心内容”与“进阶/深水区内容”的关键输入，直接影响内容是否被后置（见第 5 节）。
|
||||
|
||||
为内容精准地打上这三个维度的标签，是确保文档库结构合理、易于导航、满足不同用户需求的前提。
|
||||
|
||||
## 排序机制：**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 的[编辑与反馈按钮的自动实现](/tools/contributing_in_page.py)等所有细节。
|
||||
|
||||
## 面向受众的设计原则：渐进式披露与路径优化
|
||||
|
||||
本系统的设计贯穿着“渐进式信息披露” (Progressive Disclosure) 的核心原则，旨在优化不同背景开发者的信息获取路径。
|
||||
|
||||
1. 优先级机制 (P 值区分): 这是实现渐进式披露的主要手段。系统性地将基础、核心、高频使用的内容 (P=0) 与高级、复杂、特定场景的内容 (P=9) 分离开来。这保证了用户默认首先接触到的是一个相对精简、聚焦核心的知识体系。
|
||||
2. 结构化分类 (基于 type.primary 和 type.detail): 即便在同一优先级内，内容也被清晰地组织成不同类别和主题，为所有用户（尤其是经验丰富的用户）提供了一个可预测的“信息地图”。
|
||||
|
||||
基于以上原则，系统致力于为不同目标受众提供优化的体验：
|
||||
|
||||
- 学习者与初探者 (Learners & Newcomers, incl. Citizen Developers): 通过默认阅览 P=0 的内容序列，获得一条从概念到基础实践的、结构化的学习路径，从而循序渐进，降低初期认知负荷。
|
||||
- 经验丰富的开发者与贡献者 (Experienced Developers & Contributors): 利用清晰的结构进行高效的**随机访问**，快速定位特定参考信息或实现细节，或根据需要直接深入 P=9 的高级内容。文档库对其而言更像一本可快速查阅的技术手册。
|
||||
- 自动化工具与服务 (e.g., LLMs): 承认其与人类不同的信息消费模式。结构化的元数据**使我们能够**为其生成专门优化的、可能更扁平化的数据输入流（如 `llms-full.txt`），提升其理解效率。
|
||||
|
||||
总而言之，dimensions 系统并非试图用一种方式满足所有人，而是通过**结构化分类、优先级排序和元数据驱动的自动化**，为不同需求的用户群体提供各自相对最优的信息访问和学习路径。
|
||||
|
||||
## 系统收益
|
||||
|
||||
- 结构清晰 & 导航改善: 基于可靠的分类和可预测的排序。
|
||||
- 一致性体验: 自动化确保所有文档遵循相同模式。
|
||||
- 受众适配: 通过优先级区分，提供差异化的阅读路径。
|
||||
- 高可维护性: 调整分类或排序逻辑只需修改中心配置和脚本。
|
||||
- 可扩展性: 易于添加新的内容类型或难度级别。
|
||||
- 促进协作: 为作者、审阅者和系统维护者提供了共同的理解基础和协作标准。
|
||||
|
||||
## 创作流程、角色与治理：应对现实挑战
|
||||
|
||||
建立高质量文档库是一个涉及多方协作的过程，并面临现实挑战。dimensions 系统旨在成为这个过程中的一个结构化框架和协作工具。
|
||||
|
||||
### 协作模型中的关键角色
|
||||
|
||||
- 创作者 (Creator / Author):
|
||||
|
||||
- 核心职责: 创作准确、清晰、有价值的文档内容。
|
||||
- 协作要点: 学习并尝试理解 dimensions 分类体系，在提交时为文档**尝试**打上最合适的元数据标签（dimensions, standard_title, language）。准确的初始分类有助于后续流程。
|
||||
|
||||
- 审阅者 (Owner / Reviewer):
|
||||
|
||||
- 核心职责: 对文档内容的**准确性、清晰度、范围**以及**元数据的恰当性**进行最终把关。这是确保文档库质量和结构一致性的关键环节。
|
||||
- 能力要求: 需要具备对相关技术领域的深刻理解，**同时**要能理解 dimensions 系统背后的**整体信息架构和受众细分逻辑**（这往往需要一定的系统性思维，类似于架构师视角）。
|
||||
- 协作要点: 利用 dimensions 作为客观“标尺”来评审内容定位。如果元数据不准确或内容边界模糊，应指导创作者修改或直接修正元数据。**最终合并到主分支的元数据决定了文档的呈现**。
|
||||
|
||||
- 运营者 (Operator / DevOps):
|
||||
|
||||
- 核心职责: 维护和优化文档自动化构建、测试、部署的流程与工具。
|
||||
- 协作要点: 确保自动化脚本正确、高效地解析元数据并生成最终产物（排序的文件、导航数据等）。他们关注的是**流程的健壮性**，而非单篇文档的内容细节。
|
||||
|
||||
### 应对文档协作的现实挑战
|
||||
|
||||
这种角色划分有助于我们正视并尝试缓解一些常见的文档困境：
|
||||
|
||||
- “程序员不爱写文档” vs. “写文档的不懂技术”：
|
||||
|
||||
- dimensions 系统**降低了对创作者（程序员）的要求**：首要任务是写准技术内容，元数据分类可以“尽力而为”，因为有审阅者把关。
|
||||
- 同时，它**提升了对审阅者的要求**，承认了高质量文档需要深刻的技术理解和架构性思维，并将这种高阶能力引导到对文档结构和元数据的把控上。
|
||||
- 对于可能存在的“专职文档工程师”，他们可以作为创作者，或者辅助审阅者进行元数据校验和内容润色，角色更加灵活。
|
||||
|
||||
- 高质量审阅者稀缺且“性价比”疑虑：
|
||||
|
||||
- 确实，具备所需技术深度和架构思维的审阅者是宝贵的。他们可能会觉得审阅文档相比核心功能开发“价值较低”。
|
||||
- 关键在于提升认知： 必须强调，**高质量、结构化的文档对于开发者生态的成功、降低支持成本、提升产品采用率具有极高的战略价值**。dimensions 系统正是将审阅者的高阶思维**显性化、规范化**，并**直接转化为可衡量的文档体验提升**的工具。审阅文档不再是“杂活”，而是塑造开发者体验、构建知识体系的关键一环。
|
||||
|
||||
- 流程保障: dimensions 系统提供了一个**协作框架**。它鼓励创作者思考内容定位，赋予审阅者清晰的评估标准和修正权限，并让运营者可以独立地维护自动化流程。通过将元数据检查纳入 PR 流程（类似 Code Review），可以制度化地保障最终产出的质量。
|
||||
|
||||
## 扩展性与代码的角色
|
||||
|
||||
- 系统扩展: dimensions 的分类体系并非静态。随着 Dify 功能的演进，可以（也应该）适时增加新的 primary 类型、detail 类型或 level。这主要通过更新中央映射配置和（如有必要）调整生成脚本来实现，体现了系统的灵活性。
|
||||
- 文档与代码的关系: 开发者文档（特别是 Reference 和高级 Implementation 部分）的核心目标之一是作为理解和使用**源代码**的**有效向导**。它应解释代码层面的设计、用法、约束，并通过链接等方式促进开发者在需要时**无缝地深入到源代码**这一最终的、最精确的内容中。文档不是代码的替代品，而是其**高质量的另一面和解释器**。
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
It will be automatically generated by the script.
|
||||
*/}
|
||||
|
||||
<CardGroup cols="2">
|
||||
<Card
|
||||
title="编辑此页面"
|
||||
icon="pen-to-square"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/plugin_dev_zh/0412-doc-understanding-the-dimensions.zh.mdx"
|
||||
>
|
||||
通过直接提交修改来帮助改进文档内容
|
||||
</Card>
|
||||
<Card
|
||||
title="提交问题"
|
||||
icon="github"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=文档问题%3A%20doc-understanding-the-dimensions&body=%23%23%20问题描述%0A%3C%21--%20请简要描述您发现的问题%20--%3E%0A%0A%23%23%20页面链接%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fplugin_dev_zh%2F0412-doc-understanding-the-dimensions.zh.mdx%0A%0A%23%23%20建议修改%0A%3C%21--%20如果有具体的修改建议，请在此说明%20--%3E%0A%0A%3C%21--%20感谢您对文档质量的关注！%20--%3E"
|
||||
>
|
||||
发现错误或有改进建议？请提交问题反馈
|
||||
</Card>
|
||||
</CardGroup>
|
||||
273
plugin_dev_zh/0412-doc-writing-dimensions-guide.zh.mdx
Normal file
273
plugin_dev_zh/0412-doc-writing-dimensions-guide.zh.mdx
Normal file
@@ -0,0 +1,273 @@
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: core
|
||||
level: intermediate
|
||||
standard_title: 'Doc writing Dimensions guide'
|
||||
language: zh
|
||||
title: 'Frontmatter 元数据指南'
|
||||
summary: '了解如何使用 Dify 文档系统的元数据结构，正确定义文档属性，实现自动化组织和排序。'
|
||||
---
|
||||
|
||||
本文档帮助您快速为 Dify 开发者文档定义核心元数据。正确填写这些字段是实现文档自动化结构和排序的关键。
|
||||
|
||||
## 快速开始
|
||||
|
||||
<Tabs>
|
||||
<Tab title="使用大模型辅助">
|
||||
<Steps>
|
||||
<Step title="准备文档内容">
|
||||
完成您的文档内容撰写。
|
||||
</Step>
|
||||
<Step title="使用AI生成元数据">
|
||||
将您的文档和 [**dimensions** 系统详解](/plugin_dev_zh/0412-doc-understanding-the-dimensions.zh) 的内容交给您偏好的大模型，请求生成适合的 Frontmatter。
|
||||
</Step>
|
||||
<Step title="手动优化">
|
||||
根据实际情况和下面的详细说明，对生成的元数据进行必要的调整和优化。
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
<Tab title="手动定义">
|
||||
阅读下方的详细说明，根据您的文档内容特点，自行定义适合的元数据字段。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 必要 Frontmatter 字段
|
||||
|
||||
请在每篇 Markdown 文档的开头添加以下 YAML Frontmatter：
|
||||
|
||||
```yaml
|
||||
---
|
||||
# --- 系统核心元数据 (影响结构和排序) ---
|
||||
dimensions:
|
||||
type:
|
||||
primary: <见下方选项>
|
||||
detail: <见下方选项>
|
||||
level: <见下方选项>
|
||||
standard_title: '英文描述性标题，用于生成文件名' # e.g., 'Getting Started Dify Plugin'
|
||||
language: 'zh' # 或 'en', 'ja', etc. (ISO 639-2 代码)
|
||||
|
||||
# --- 页面内容元数据 (可选，但推荐) ---
|
||||
title: '文档的 H1 标题或页面标题'
|
||||
description: '文档内容的简短 SEO 描述'
|
||||
# summary: '更详细的摘要 (可选)'
|
||||
# tags: ['关键词'] (可选)
|
||||
---
|
||||
```
|
||||
|
||||
## `dimensions` 字段详解
|
||||
|
||||
<Tabs>
|
||||
<Tab title="type.primary">
|
||||
<CardGroup cols={2}>
|
||||
<Card title="conceptual" icon="lightbulb">
|
||||
**概念、理论** (是什么/为什么)
|
||||
<br />重点解释概念和基础理论
|
||||
</Card>
|
||||
<Card title="implementation" icon="code">
|
||||
**开发实践、代码** (如何做)
|
||||
<br />重点提供实现步骤和代码示例
|
||||
</Card>
|
||||
<Card title="operational" icon="gears">
|
||||
**运维、部署** (如何运行)
|
||||
<br />重点关注系统运行和维护
|
||||
</Card>
|
||||
<Card title="reference" icon="book">
|
||||
**API、配置参考** (精确查找)
|
||||
<br />重点提供技术规格和参考信息
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</Tab>
|
||||
|
||||
<Tab title="type.detail">
|
||||
在 `primary` 类别下的细分：
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="conceptual 下的细分" icon="lightbulb">
|
||||
<ul>
|
||||
<li><code>introduction</code>: 入门介绍</li>
|
||||
<li><code>principles</code>: 设计原则</li>
|
||||
<li><code>architecture</code>: 架构说明</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="implementation 下的细分" icon="code">
|
||||
<ul>
|
||||
<li><code>basic</code>: 基础实现</li>
|
||||
<li><code>standard</code>: 标准实现</li>
|
||||
<li><code>high</code>: 高级实现 (可能后置)</li>
|
||||
<li><code>advanced</code>: 深度实现 (可能后置)</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="operational 下的细分" icon="gears">
|
||||
<ul>
|
||||
<li><code>setup</code>: 环境设置</li>
|
||||
<li><code>deployment</code>: 部署操作</li>
|
||||
<li><code>maintenance</code>: 维护管理</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="reference 下的细分" icon="book">
|
||||
<ul>
|
||||
<li><code>core</code>: 核心参考</li>
|
||||
<li><code>configuration</code>: 配置参考</li>
|
||||
<li><code>examples</code>: 示例参考</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
更多选项请参考 [dimensions 系统详解](/plugin_dev_zh/0412-doc-understanding-the-dimensions.zh) 文档
|
||||
</Note>
|
||||
</Tab>
|
||||
|
||||
<Tab title="level">
|
||||
<CardGroup cols={3}>
|
||||
<Card title="beginner" icon="seedling">
|
||||
**新手入门**
|
||||
<br />适合初学者的入门内容
|
||||
</Card>
|
||||
<Card title="intermediate" icon="tree">
|
||||
**常规用户**
|
||||
<br />适合有一定基础的用户
|
||||
</Card>
|
||||
<Card title="advanced" icon="mountain">
|
||||
**高级用户**
|
||||
<br />适合专业用户的深入内容 (通常会被后置排序)
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 其他重要字段
|
||||
|
||||
<ResponseField name="standard_title" type="string" required>
|
||||
使用**英文**，清晰描述文档核心内容。系统将用它生成部分文件名 (例如 `Getting Started Dify Plugin`)。
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="language" type="string" required>
|
||||
ISO 639-2 双字母语言代码 (如 `en`, `zh`, `ja`)。
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="title" type="string" recommended>
|
||||
文档在页面上显示的主标题，通常是本地化语言。
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="description" type="string" recommended>
|
||||
简短的SEO描述，用于搜索引擎和预览。
|
||||
</ResponseField>
|
||||
|
||||
## 完整示例
|
||||
|
||||
<CodeGroup>
|
||||
```yaml 入门文档示例
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: conceptual
|
||||
detail: introduction
|
||||
level: beginner
|
||||
standard_title: 'Getting Started Dify Plugin'
|
||||
language: zh
|
||||
title: '欢迎开始 Dify 插件开发'
|
||||
description: '介绍Dify插件的概念、功能和开发价值，包括插件类型的简要说明，以及开发者文档的内容概览。'
|
||||
---
|
||||
```
|
||||
|
||||
```yaml 工具开发文档示例
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: implementation
|
||||
detail: standard
|
||||
level: intermediate
|
||||
standard_title: 'Developing Tool Plugin'
|
||||
language: zh
|
||||
title: '开发工具插件'
|
||||
description: '详细指导如何创建和配置Dify工具插件，包括API调用、数据处理和用户界面集成方面的实践指南。'
|
||||
---
|
||||
```
|
||||
|
||||
```yaml 参考文档示例
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: configuration
|
||||
level: intermediate
|
||||
standard_title: 'Plugin Manifest Configuration'
|
||||
language: zh
|
||||
title: '插件配置清单参考'
|
||||
description: '全面说明插件配置文件(manifest.json)的各项参数设置、格式要求和应用场景。'
|
||||
---
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Tip>
|
||||
**解读示例:** 第一个例子是一篇面向初学者的、关于 Dify 插件概念的入门介绍文档，语言为中文。系统会根据元数据自动将其正确放置在文档结构中。
|
||||
</Tip>
|
||||
|
||||
## 文档自动化处理
|
||||
|
||||
<Tabs>
|
||||
<Tab title="本地开发">
|
||||
运行 `tools/main_docs_bundle.py`，文档将被自动根据 Frontmatter 完成以下操作：
|
||||
|
||||
<Steps>
|
||||
<Step title="重命名文件">
|
||||
系统将根据 dimensions 和 standard_title 自动生成标准化文件名。
|
||||
</Step>
|
||||
<Step title="更新导航">
|
||||
文档将被自动注入到 docs.json 导航配置中。
|
||||
</Step>
|
||||
<Step title="添加交互组件">
|
||||
自动刷新贡献和反馈按钮等交互组件。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Info>
|
||||
在本地环境开发文档时，建议运行该脚本确保文档配置正确生效。
|
||||
</Info>
|
||||
</Tab>
|
||||
|
||||
<Tab title="GitHub 编辑">
|
||||
|
||||
如果您在 GitHub 上直接进行编辑，**无需担心**自动化步骤。我们已经配置了 GitHub Action 等自动化工具，会在以下情况自动执行 `tools/main_docs_bundle.py`：
|
||||
|
||||
- 当您提交 Pull Request 时
|
||||
- 当您的更改被合并到主分支时
|
||||
|
||||
<Check>
|
||||
您可以专注于内容创作，GitHub 工作流会处理文件重命名、导航更新和交互组件生成等技术细节。
|
||||
</Check>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Card title="想了解更多？" icon="book-open" href="/plugin_dev_zh/0412-doc-understanding-the-dimensions.zh">
|
||||
如果您对 Dimensions 系统的设计理念、排序机制的完整细节或角色与治理感兴趣，请阅读完整的 Dimensions 系统详解文档。
|
||||
</Card>
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
It will be automatically generated by the script.
|
||||
*/}
|
||||
|
||||
<CardGroup cols="2">
|
||||
<Card
|
||||
title="编辑此页面"
|
||||
icon="pen-to-square"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/plugin_dev_zh/0412-doc-writing-dimensions-guide.zh.mdx"
|
||||
>
|
||||
通过直接提交修改来帮助改进文档内容
|
||||
</Card>
|
||||
<Card
|
||||
title="提交问题"
|
||||
icon="github"
|
||||
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=文档问题%3A%20doc-writing-dimensions-guide&body=%23%23%20问题描述%0A%3C%21--%20请简要描述您发现的问题%20--%3E%0A%0A%23%23%20页面链接%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fplugin_dev_zh%2F0412-doc-writing-dimensions-guide.zh.mdx%0A%0A%23%23%20建议修改%0A%3C%21--%20如果有具体的修改建议，请在此说明%20--%3E%0A%0A%3C%21--%20感谢您对文档质量的关注！%20--%3E"
|
||||
>
|
||||
发现错误或有改进建议？请提交问题反馈
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -1,212 +1,5 @@
|
||||
# Dify 开发者文档结构化与排序规范：**dimensions** 系统详解
|
||||
# Dify 插件开发者文档
|
||||
|
||||
## 目录
|
||||
本指南旨在帮助开发者快速上手 Dify 插件开发，提供必要的文档和资源链接。
|
||||
|
||||
- [Dify 开发者文档结构化与排序规范：**dimensions** 系统详解](#dify-开发者文档结构化与排序规范dimensions-系统详解)
|
||||
- [目录](#目录)
|
||||
- [背景与动机：应对开发者生态的演进](#背景与动机应对开发者生态的演进)
|
||||
- [核心原则：元数据作为规范性数据源](#核心原则元数据作为规范性数据源)
|
||||
- [元数据规范](#元数据规范)
|
||||
- [dimensions 深度解析：为内容赋予意义](#dimensions-深度解析为内容赋予意义)
|
||||
- [排序机制：**PWXY** 前缀与优先级规则](#排序机制pwxy-前缀与优先级规则)
|
||||
- [文件名生成策略](#文件名生成策略)
|
||||
- [面向受众的设计原则：渐进式披露与路径优化](#面向受众的设计原则渐进式披露与路径优化)
|
||||
- [系统收益](#系统收益)
|
||||
- [创作流程、角色与治理：应对现实挑战](#创作流程角色与治理应对现实挑战)
|
||||
- [协作模型中的关键角色](#协作模型中的关键角色)
|
||||
- [应对文档协作的现实挑战](#应对文档协作的现实挑战)
|
||||
- [扩展性与代码的角色](#扩展性与代码的角色)
|
||||
|
||||
---
|
||||
|
||||
## 背景与动机：应对开发者生态的演进
|
||||
|
||||
Dify 最初的成功很大程度上源于其产品的直观易用性。对于核心用户（User/Buyer），产品本身的体验往往足以引导他们；对于少数需要深度定制的早期开发者而言，他们通常具备直接阅读源代码的能力。因此，初期的文档建设并非最高优先级。
|
||||
|
||||
然而，随着 **Dify Plugin 插件生态的上线和蓬勃发展**，情况发生了显著变化：
|
||||
|
||||
1. 受众扩大化： 我们的开发者社区不再局限于能够深入源码的核心贡献者。大量拥有一定技术背景但可能不熟悉 Dify 底层或特定编程范式的**“半专业开发者” (Citizen Developers)** 或集成开发者涌现，他们需要清晰、循序渐进的指导来构建和贡献插件。
|
||||
2. 内容交织与目标模糊： 现有的文档往往将面向最终用户的**帮助内容**（如何使用插件）与面向开发者的**技术内容**（如何开发插件）混合在一起，导致两类受众都感到困惑，增加了信息查找成本。
|
||||
3. 结构缺失与导航困难： 文档缺乏统一的组织结构和逻辑顺序，使得开发者（尤其是新加入者）难以找到所需信息，也无法形成对插件开发生命周期的完整认知。现有导航难以承载日益增长的内容。
|
||||
4. 构建开发者关系 (DevRel) 的基石： 一个清晰、有效、结构优异的开发者文档体系，是构建成功开发者关系、繁荣插件生态不可或缺的一环。它直接影响开发者的体验、贡献意愿和成功率。
|
||||
|
||||
基于以上挑战，以及对业界优秀范例（如 Zapier Developer Platform, Cloudflare Docs）的分析——它们都展现了清晰的受众分离、结构化的内容组织和面向不同技能水平的路径设计——我们认识到对 Dify 的开发者文档进行**系统性重构**的迫切性。
|
||||
|
||||
dimensions**系统**应运而生。它并非一套僵化的格式要求，而是我们为了解决上述问题，将**结构化思维、受众细分、渐进式学习**等理念，通过一套**基于元数据的自动化流程**沉淀下来的解决方案。它旨在为 Dify 插件开发者提供一个清晰、一致且易于导航的技术知识库。
|
||||
|
||||
## 核心原则：元数据作为规范性数据源
|
||||
|
||||
本系统的基石在于以下核心原则：
|
||||
|
||||
- 元数据驱动 (Metadata-Driven): 每篇 Markdown 文档的 Front Matter 中定义的元数据（特别是 dimensions, standard_title, language）是描述该文档内容属性、目标受众和预期用途的**规范性数据源 (Normative Data Source)**。
|
||||
- 内容与表现分离 (Decoupling Content from Presentation): 文档的最终呈现形式——包括文件名、在文档网站上的排序、导航菜单结构——都**必须由自动化工具根据这些元数据动态生成**。作者应专注于内容本身及其元数据描述的准确性。
|
||||
- 自动化保障一致性与可维护性 (Automation for Consistency & Maintainability): 自动化流程确保了整个文档库在结构、命名和排序上的一致性。对分类体系或排序逻辑的调整，只需修改中央配置和生成脚本即可全局应用，极大地提高了可维护性。
|
||||
|
||||
这种方法论让内容创作者（作者）和技术实现者（文档系统维护者/DevOps）能够有效协作，共同服务于最终开发者读者的需求。
|
||||
|
||||
## 元数据规范
|
||||
|
||||
每篇开发者文档（Markdown 文件）必须包含一个 YAML Front Matter 块，定义如下关键字段：
|
||||
|
||||
```yaml
|
||||
---
|
||||
# --- 核心元数据 ---
|
||||
|
||||
# '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') 用于国际化(i18n)和文件名后缀
|
||||
language: <language_code>
|
||||
|
||||
# --- 其他可选元数据 ---
|
||||
|
||||
# 'summary': 文档内容的简短摘要 (可选, 可能用于列表页或 SEO)
|
||||
# 'tags': [关键词列表] (可选, 用于过滤或关联内容)
|
||||
# ... 其他未来可能需要的字段
|
||||
---
|
||||
```
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## dimensions 深度解析：为内容赋予意义
|
||||
|
||||
dimensions 元数据是本系统的核心，它要求我们为每一篇文档回答三个基本问题，从而赋予其明确的**语境、范围和受众定位**。这种分类是后续所有自动化结构和排序的基础。
|
||||
|
||||
- dimensions.type.primary：定义内容的“性质”
|
||||
|
||||
- 核心问题: 这篇文档从根本上属于哪一类知识？它是关于“是什么/为什么”（理论），“如何做”（实践），“如何运行/维护”（运维），还是“精确查找”（参考）？
|
||||
- 作用: 这个维度确立了文档在整个知识体系中的**宏观类别**。我们采用 conceptual, implementation, operational, reference 这几个业界通用的分类，来划分开发者关注的主要领域。这个分类决定了文档所属的**顶层章节**或主题区域，是构建文档信息架构的第一步。
|
||||
|
||||
- dimensions.type.detail：明确内容的“主题焦点”
|
||||
|
||||
- 核心问题: 在上述宏观类别下，这篇文档具体是关于该类别的哪个**特定方面或子主题**？例如，是某个概念的“入门介绍”，还是某个实现的“标准用法”，或是某个参考信息的“核心 API”？
|
||||
- 作用: 它在主类别内部提供了**更精细的主题划分**。这使得相关的文档能够聚集在一起，形成逻辑连贯的**子章节**或段落。选择恰当的 detail 有助于用户在浏览特定章节时快速定位到具体内容点。
|
||||
|
||||
- dimensions.level：标定内容的“复杂度与受众”
|
||||
- 核心问题: 这篇特定主题的文档，主要是为哪个**经验水平的读者**准备的？或者说，其内容的**复杂度**如何？是入门 (beginner)，通用 (intermediate)，还是深入/专门 (advanced)？
|
||||
- 作用: 这个维度具有**双重关键作用**：
|
||||
1. 细粒度排序: 在同一具体主题下，它允许内容按从易到难的顺序排列，优化学习曲线。
|
||||
2. 优先级判定: 它（尤其是 advanced 级别）是系统区分“核心内容”与“进阶/深水区内容”的关键输入，直接影响内容是否被后置（见第 5 节）。
|
||||
|
||||
为内容精准地打上这三个维度的标签，是确保文档库结构合理、易于导航、满足不同用户需求的前提。
|
||||
|
||||
## 排序机制：**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 的[编辑与反馈按钮的自动实现](/tools/contributing_in_page.py)等所有细节。
|
||||
|
||||
## 面向受众的设计原则：渐进式披露与路径优化
|
||||
|
||||
本系统的设计贯穿着“渐进式信息披露” (Progressive Disclosure) 的核心原则，旨在优化不同背景开发者的信息获取路径。
|
||||
|
||||
1. 优先级机制 (P 值区分): 这是实现渐进式披露的主要手段。系统性地将基础、核心、高频使用的内容 (P=0) 与高级、复杂、特定场景的内容 (P=9) 分离开来。这保证了用户默认首先接触到的是一个相对精简、聚焦核心的知识体系。
|
||||
2. 结构化分类 (基于 type.primary 和 type.detail): 即便在同一优先级内，内容也被清晰地组织成不同类别和主题，为所有用户（尤其是经验丰富的用户）提供了一个可预测的“信息地图”。
|
||||
|
||||
基于以上原则，系统致力于为不同目标受众提供优化的体验：
|
||||
|
||||
- 学习者与初探者 (Learners & Newcomers, incl. Citizen Developers): 通过默认阅览 P=0 的内容序列，获得一条从概念到基础实践的、结构化的学习路径，从而循序渐进，降低初期认知负荷。
|
||||
- 经验丰富的开发者与贡献者 (Experienced Developers & Contributors): 利用清晰的结构进行高效的**随机访问**，快速定位特定参考信息或实现细节，或根据需要直接深入 P=9 的高级内容。文档库对其而言更像一本可快速查阅的技术手册。
|
||||
- 自动化工具与服务 (e.g., LLMs): 承认其与人类不同的信息消费模式。结构化的元数据**使我们能够**为其生成专门优化的、可能更扁平化的数据输入流（如 `llms-full.txt`），提升其理解效率。
|
||||
|
||||
总而言之，dimensions 系统并非试图用一种方式满足所有人，而是通过**结构化分类、优先级排序和元数据驱动的自动化**，为不同需求的用户群体提供各自相对最优的信息访问和学习路径。
|
||||
|
||||
## 系统收益
|
||||
|
||||
- 结构清晰 & 导航改善: 基于可靠的分类和可预测的排序。
|
||||
- 一致性体验: 自动化确保所有文档遵循相同模式。
|
||||
- 受众适配: 通过优先级区分，提供差异化的阅读路径。
|
||||
- 高可维护性: 调整分类或排序逻辑只需修改中心配置和脚本。
|
||||
- 可扩展性: 易于添加新的内容类型或难度级别。
|
||||
- 促进协作: 为作者、审阅者和系统维护者提供了共同的理解基础和协作标准。
|
||||
|
||||
## 创作流程、角色与治理：应对现实挑战
|
||||
|
||||
建立高质量文档库是一个涉及多方协作的过程，并面临现实挑战。dimensions 系统旨在成为这个过程中的一个结构化框架和协作工具。
|
||||
|
||||
### 协作模型中的关键角色
|
||||
|
||||
- 创作者 (Creator / Author):
|
||||
|
||||
- 核心职责: 创作准确、清晰、有价值的文档内容。
|
||||
- 协作要点: 学习并尝试理解 dimensions 分类体系，在提交时为文档**尽力**打上最合适的元数据标签（dimensions, standard_title, language）。准确的初始分类有助于后续流程。
|
||||
|
||||
- 审阅者 (Owner / Reviewer):
|
||||
|
||||
- 核心职责: 对文档内容的**准确性、清晰度、范围**以及**元数据的恰当性**进行最终把关。这是确保文档库质量和结构一致性的关键环节。
|
||||
- 能力要求: 需要具备对相关技术领域的深刻理解，**同时**要能理解 dimensions 系统背后的**整体信息架构和受众细分逻辑**（这往往需要一定的系统性思维，类似于架构师视角）。
|
||||
- 协作要点: 利用 dimensions 作为客观“标尺”来评审内容定位。如果元数据不准确或内容边界模糊，应指导创作者修改或直接修正元数据。**最终合并到主分支的元数据决定了文档的呈现**。
|
||||
|
||||
- 运营者 (Operator / DevOps / SRE / Doc System Maintainer):
|
||||
|
||||
- 核心职责: 维护和优化文档自动化构建、测试、部署的流程与工具。
|
||||
- 协作要点: 确保自动化脚本正确、高效地解析元数据并生成最终产物（排序的文件、导航数据等）。他们关注的是**流程的健壮性**，而非单篇文档的内容细节。
|
||||
|
||||
### 应对文档协作的现实挑战
|
||||
|
||||
这种角色划分有助于我们正视并尝试缓解一些常见的文档困境：
|
||||
|
||||
- “程序员不爱写文档” vs. “写文档的不懂技术”：
|
||||
|
||||
- dimensions 系统**降低了对创作者（程序员）的要求**：首要任务是写准技术内容，元数据分类可以“尽力而为”，因为有审阅者把关。
|
||||
- 同时，它**提升了对审阅者的要求**，承认了高质量文档需要深刻的技术理解和架构性思维，并将这种高阶能力引导到对文档结构和元数据的把控上。
|
||||
- 对于可能存在的“专职文档工程师”，他们可以作为创作者，或者辅助审阅者进行元数据校验和内容润色，角色更加灵活。
|
||||
|
||||
- 高质量审阅者稀缺且“性价比”疑虑：
|
||||
|
||||
- 确实，具备所需技术深度和架构思维的审阅者是宝贵的。他们可能会觉得审阅文档相比核心功能开发“价值较低”。
|
||||
- 关键在于提升认知： 必须强调，**高质量、结构化的文档对于开发者生态的成功、降低支持成本、提升产品采用率具有极高的战略价值**。dimensions 系统正是将审阅者的高阶思维**显性化、规范化**，并**直接转化为可衡量的文档体验提升**的工具。审阅文档不再是“杂活”，而是塑造开发者体验、构建知识体系的关键一环。
|
||||
|
||||
- 流程保障: dimensions 系统提供了一个**协作框架**。它鼓励创作者思考内容定位，赋予审阅者清晰的评估标准和修正权限，并让运营者可以独立地维护自动化流程。通过将元数据检查纳入 PR 流程（类似 Code Review），可以制度化地保障最终产出的质量。
|
||||
|
||||
## 扩展性与代码的角色
|
||||
|
||||
- 系统扩展: dimensions 的分类体系并非静态。随着 Dify 功能的演进，可以（也应该）适时增加新的 primary 类型、detail 类型或 level。这主要通过更新中央映射配置和（如有必要）调整生成脚本来实现，体现了系统的灵活性。
|
||||
- 文档与代码的关系: 开发者文档（特别是 Reference 和高级 Implementation 部分）的核心目标之一是作为理解和使用**源代码**的**有效向导**。它应解释代码层面的设计、用法、约束，并通过链接等方式促进开发者在需要时**无缝地深入到源代码**这一最终的、最精确的内容中。文档不是代码的替代品，而是其**高质量的另一面和解释器**。
|
||||
贡献指南: [Dify Docs](https://docs.dify.ai/plugin_dev_zh/0411-doc-contribution-guide.zh)
|
||||
|
||||
Reference in New Issue
Block a user