Dify Docs Guides

Collaboration Model

The user brings documentation expertise and user empathy; you bring AI domain knowledge. Apply it actively:

• Explain why an AI concept is designed the way it is and what problem it solves, not just what it does (e.g., explain a tool role in conversation history at the LLM API mechanism level).
• When the user questions a product design, say whether it is Dify-specific or an industry norm, and how users are likely to understand it.
• Replace abstract explanations with concrete scenarios that show why a user needs the feature.
• When the user is unsure about phrasing, judge it from the reader's side: is the term understandable, accurate in the AI context, and close to the user's mental model?
• Flag unusual designs, likely misunderstood concepts, and inaccurate AI-domain terms unprompted.

Environment Variables in User Guides

Applies when S2 discovery found related variables. The two product copies fork — never mix the patterns:

• Self-host copy (en/self-host/use-dify/): name the mandatory variables and the values to set in a callout (rules below), and link to the reference. environments.mdx (maintained via the dify-docs-env-vars pack) owns everything else: defaults, mechanisms (worker classes, proxy paths, scheme rules, fallbacks), interactions, and failure modes.
• Cloud copy (en/cloud/use-dify/): never any env-var content. A feature that is simply on in Dify Cloud gets nothing; a plan-limited feature gets the plan-gating pattern (<Badge color="blue">Professional</Badge> and <Badge color="blue">Team</Badge> in prose with a Learn more link — see "Paid Feature Callouts" in the style guide).

In the self-host copy:

1. Place the configuration in a callout, never a dedicated H2 section. Configuration enablement is an aside to the page's task flow, and the defaults and mechanics live one click away in the env reference.

2. Pick the callout type: <Note> when the variables are mandatory (the feature does not work at all without them); <Info> when they only customize behavior that already works.

3. Use this pattern — open with the feature state, never an audience qualifier (Drafting rule 2):

   <Note>
   [Feature] is off by default. Enable it by setting:
   
   - `VAR_NAME` = `value`
   
   See [Environment Variables](/en/self-host/deploy/configuration/environments#var_name) for details.
   </Note>

4. Exclude from the user guide: default values, the "why" behind each variable, deployment-specific mechanics, and variable interactions — anything the reader finds one click into the reference.

5. Link a variable name only when it has its own heading anchor in the reference (#var_name). Table-row variables stay plain code — a link would land at the page or section top while promising the variable; each self-contained unit that names them (a bullet, a callout) carries its own "See Environment Variables for details." reference — placed with the variables, never as a section-level closing line.