Dify Docs Guides

User Guide Rules

Not an entry point — run under dify-docs-write; this pack's rules and procedures implement its stages for user-guide pages.

Scoping rules (S1)

Match each target page to its reader persona (see Reader Personas below). use-dify pages exist as two product copies — en/cloud/use-dify/ and en/self-host/use-dify/ — with no shared pages and no cross-audience navigation. When the page exists in both, scope both: shared-content improvements land in both copies in the same pass; audience-specific blocks (plan gating, env-var callouts, Enterprise tips) stay per-copy. Exception — work on a release/<version> branch edits only the self-host copy, still in all three languages; what it excludes is the cloud copy, which follows Cloud's own release lane (see the dify-docs-release-sync skill § Docs Branch).

S2 discovery — environment variables

Check for feature-related environment variables. In the Dify codebase, run:

grep -rn "<FEATURE_KEYWORD>" docker/.env.example docker/envs/ api/configs/

Use the feature's name as it would appear in a variable (e.g. COLLABORATION); try 2–3 keyword variants before concluding. No matches → the feature has no env-var surface; skip the env-var guidance below. Matches → record each variable as mandatory or optional plus its default, and queue the dify-docs-env-vars pack's procedure in the S4 scope report, to update en/self-host/deploy/configuration/environments.mdx in the same session — that reference is the single source of truth for variable semantics.

Drafting rules (S5)

1. Write for the persona of the page's path (see Reader Personas below).
2. A page doesn't restate its own audience. Everyone on a self-host page is self-hosted and everyone on a cloud page is on Dify Cloud, so "On self-hosted deployments, …" and "On Dify Cloud, …" tell those readers nothing; qualifiers earn their place only on the audience-neutral trees (en/learn/, en/api-reference/, en/cli/, en/develop-plugin/), where they disambiguate. Two uses are different in kind and belong: naming a different product (the <Tip> surfacing Dify Enterprise where a CE capability ends, per "Paid Feature Callouts" in the style guide), and a comparative-advantage claim, where the qualifier marks something this product has that the other lacks ("On Dify Cloud, many popular trigger integrations are pre-configured" is about the perk, not the scope).
3. If S2 discovery found related environment variables, present them per Environment Variables in User Guides below.

Reader Personas

Adjust tone and assumed knowledge by document path. This is the master copy of these personas; other skills point here.

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.