dify-docs-guides

name	dify-docs-guides
description	Use when writing, improving, or reviewing Dify user guide documentation. Covers pages in en/{cloud,self-host}/use-dify/, en/develop-plugin/, and en/self-host/deploy/. Triggers: "write docs for [feature]", "improve this page", "review this documentation section".

Dify Documentation Guides

Before Starting

Read these files before beginning any documentation task:

1. writing-guides/style-guide.md — voice, tone, writing patterns
2. writing-guides/formatting-guide.md — MDX formatting, Mintlify components
3. writing-guides/glossary.md — standardized terminology

When optimizing Chinese or Japanese translations, also read:

• tools/translate/formatting-zh.md or tools/translate/formatting-ja.md

Reader Personas

Adjust tone and assumed knowledge based on the document path:

en/{cloud,self-host}/use-dify/

Product users building AI applications on Dify. Mix of developers and non-technical users. Assume basic AI familiarity but not infrastructure or deep coding knowledge. Explain technical concepts when they appear. Prioritize task completion and outcomes.

en/self-host/deploy/

DevOps engineers and system administrators deploying Dify. Assume strong infrastructure knowledge (Docker, databases, networking, environment variables). Be precise with technical details. Don't over-explain standard operations.

en/develop-plugin/

Developers building custom Dify plugins. Assume strong Python skills and familiarity with Dify's core concepts. Focus on API contracts, extension points, and code patterns. Code examples are essential.

Collaboration Model

This is a team effort. The user brings documentation expertise and user empathy; Claude brings AI domain knowledge and broader technical perspective. Actively leverage this dynamic rather than passively executing writing tasks.

Explain the "why" behind AI concepts. When an AI concept comes up, explain why it's designed this way and what problem it solves—not just what it does. For example, if asked why a tool role appears in conversation history, explain from the LLM API mechanism level.

Help judge design decisions. When the user questions a product design: assess whether it's common in the AI field, clarify if it's Dify-specific or industry standard, and offer perspective on how users might understand it.

Provide analogies and concrete scenarios. When concepts are abstract, use specific scenarios rather than technical jargon. Help the user understand "why users need this feature" from a practical standpoint.

Analyze wording from user cognition perspective. When the user is unsure about phrasing, consider: Can users understand this term? Is it accurate in the AI context? Is there a term closer to the user's mental model?

Proactively flag issues. If a design seems unusual, a concept may have been misunderstood, or a term is inaccurate in the AI domain—speak up directly rather than waiting to be asked.

Verifying Feature Behavior

• Pull the latest Dify code before verifying. git fetch origin, then fast-forward main only if the working tree is clean (substitute the branch if the user specifies one); don't force a checkout over a dirty or feature tree.
• For existing features: verify against the main branch of the Dify codebase. The user will provide the codebase path or it will be configured as an additional working directory.
• For new features: the user may specify a development branch. Code may be in flux—when behavior is ambiguous, ask rather than assume.
• Trust the codebase over existing documentation. Existing docs may be outdated or inaccurate.
• When rewriting an existing page, re-verify every claim you carry over (permissions, defaults, option lists, navigation paths, behavior). Treat the original page as unverified and confirm each fact against the code before keeping it. The most common failure mode is faithfully reproducing an outdated section.
• Code presence ≠ working feature. A code path existing does not guarantee the feature functions end to end. When behavior is inferred from code analysis rather than observed in the running product, flag it as unverified and ask the user to test before documenting it as fact.

Environment Variables in User Guides

When a feature is gated by or configured through environment variables (feature toggles, endpoints, self-host-only switches, worker classes), coordinate with the reference doc instead of duplicating it.

Investigate first

During feature research, check whether the feature has related environment variables:

• Grep docker/.env.example, api/configs/, and the feature's PR for any ENABLE_*, *_URL, worker, or socket settings tied to the feature.
• Note which variables are mandatory vs. optional, and what their defaults are.

If the feature has related variables, use the dify-docs-env-vars skill to update en/self-host/deploy/configuration/environments.mdx in the same session. The reference doc is the single source of truth for variable semantics.

Division of responsibility

• Environment Variable Reference (en/self-host/deploy/configuration/environments.mdx): exhaustive. Every variable gets a description covering purpose, defaults, interactions, and failure modes. Maintained via the dify-docs-env-vars skill.
• User Guide: functional only. Name the mandatory variables and the values to set, then link to the reference. Do not re-explain the mechanism (WebSocket paths, worker classes, scheme rules, fallback behavior). Those details live in the reference.

How to present in the User Guide

User Guides serve both SaaS (Dify Cloud) and self-hosted readers. Place self-host-only configuration in a callout rather than a dedicated H2 section. The callout surfaces the information clearly for self-hosters while letting SaaS readers skip past it without breaking the flow of the guide.

Choose the callout type by what the variables do:

• <Note> — when the variables are mandatory for the feature to work. Without them, self-hosters will not be able to use the feature at all. Example: ENABLE_COLLABORATION_MODE gates the entire collaboration feature.
• <Info> — when the variables only customize existing behavior (tuning a default, switching backends, adjusting an endpoint). The feature works without them; these are optional knobs.

Pattern (substitute <Note> or <Info> per the rule above):

<Note>
On self-hosted deployments, [feature] is turned off by default. Enable it by setting:

- `VAR_NAME` = `value`
- ...

See [Environment Variables](/en/self-host/deploy/configuration/environments#var_name) for details.
</Note>

Do not promote self-host config to an H2 section. Giving deployment-specific content equal weight with product-facing content clutters the guide for SaaS readers, who are the majority of the audience.

What to exclude from the User Guide

• Default values already covered in the reference.
• The "why" behind each variable: worker types, proxy paths, scheme rules, fallback behavior.
• Custom-domain examples, deployment-specific mechanics, or variable interactions.
• Anything a reader could find by clicking through to the reference.

Style Overrides

No overrides. Follow writing-guides/style-guide.md as written.

Post-Writing Verification

After completing the document, run the post-writing checks listed in writing-guides/index.md#post-writing-verification.