Dify Docs Write

Writing Dify Documentation

The deliverable is a page a reader can use: accurate against the shipped product, written for the moment they arrive with, in the fewest words that stay clear. The standard is the style guide, above all its opening section, "What a Good Page Does"; the two reference pages it names calibrate register beside it. The checks catch what a reader pass can miss; passing them is a floor, not the standard.

Each stage below names what it reads. Read at the stage, not before: the drafting turn should hold the bar and the facts, not the check procedures.

Route

Pick the rule pack from the target path (most specific match wins). When the target repo carries an AGENTS.md, its repo-wide rules apply on top. A page with no pack skips every pack read below; the guides alone govern it. The pack carries what is specific to its surface. When they disagree, the guides win, over this skill too.

Read now: writing-guides/style-guide.md; the pack's reader and vocabulary sections; the glossary rows for the surfaces in scope (writing-guides/glossary.md, by UI label, not the whole file).

Understand before you write (S1–S3)

Read now: writing-guides/index.md § "Syncing the Dify codebase safely"; the pack's procedures labeled S2; references/task-analysis.md; references/research-summary.md.

Pin the code ref first (for a pre-release feature, the development branch the user names) and verify every claim there. Existing docs are not evidence, because pages go stale, so a rewrite re-checks everything it keeps. Code presence is not a working feature either: behavior inferred from code rather than confirmed is reported as unverified and stays off the page, and so is a claim whose source you cannot reach, marked UNVERIFIED in the scope report and the PR description. The depth follows the job. A correction verifies the one disputed claim and records the evidence. An update runs dify-docs-feature-research at targeted depth on the surfaces the change touches. A new page, a rewrite, or a pre-release feature runs dify-docs-feature-research in full, and a rewrite re-verifies every claim carried over. Run the pack's S2 discovery and record each result, including "no match".

Write the research down, from the research skill's record, as the drafter will need it, in the shape references/research-summary.md shows, because the drafter mirrors the shape and vocabulary of what it is handed and the summary's frame decides what it does with a fact. The session decides what the page does not carry; the drafter decides, sentence by sentence, what the reader would ask for, and a summary trimmed to exactly the page leaves it nothing to decide.

Then work out who arrives at this page and what they are trying to do, with references/task-analysis.md. Tasks come from the reader's own journeys through the product, not from the issue text or the code trace. For each task, note what they need before starting, what they will wonder mid-way, what they will overlook, and how they will know it worked. What the interface shows at that moment stays out; what it cannot show goes in. A question the docs cannot answer (a UI gap, a product gap) is reported, never papered over in prose.

For a use-dify page, both audience copies are in scope: shared improvements land in both, audience-specific blocks stay per copy (the guides pack has the rules).

Agree the scope (S4)

Before drafting, report the pages and what will change on each, the research summary itself, the unverified claims, and the questions you are routing elsewhere, then stop for approval. Silent scope drift is the failure this guards against, and the summary is shown so the owner can check the question each section answers and strike facts a reader would not ask for before a drafter states them. A single-page correction, or a task arriving from a maintainer's already-approved release-sync report, proceeds without the stop. When the scope offers a structural choice, give each option's reader impact and size before asking for a decision. A port into another tree is scoped from the feature's full footprint in the source tree (the union of its source PRs' file lists, a link sweep, and a name sweep), never from the target tree or a parked branch, and every footprint file gets an include, adapt, or exclude line. When no reviewer is in the session, put the report in the PR description and continue; the approval happens at PR review.

Write (S5)

Read now: the pack's procedures labeled S5 and the references they name (page shape, conventions, style overrides). Then, last before the first sentence: the whole style guide, whose opening section "What a Good Page Does" is the standard and whose later sections carry the rules only a drafter can apply (plan badges, the Enterprise tip, how limits are phrased, location-first instructions); references/drafting-turn.md; and the reference page in the page's genre, en/cloud/use-dify/build/new-agent/overview.mdx for a concept page or en/cloud/use-dify/build/new-agent/build.mdx for a task page. A reference page (a CLI command, an API group, a node) takes the task page plus the pack's page shape: the pack decides the sections, tables, and conventions of its document type, and the sample decides only how the sentences inside them sound. The two pages calibrate register; the style guide is the authority when they differ.

For a new page or a rewrite, the outline is the summary's question-headed sections in the reader's order; the owner approved it with the summary, so re-propose only what changed since. Exclusions need no defense; an inclusion that answers no question is the thing to defend.

Before handing off, propose how the drafting splits and agree it with the owner (the no-reviewer rule under Agree the scope applies): pages that share a through-line go to one drafter as one topic, the touched sections of related pages go to one drafter by topic on a partial edit, and one drafter per page is a choice, not the default.

The session that did the research never drafts: its context is full of code vocabulary, tool output, and its own history, and the prose takes that register.

The drafter gets the filled-in reader block at the top of its turn, the research summary, the whole style guide, references/drafting-turn.md, the reference page in its genre, and the pack's page-shape and drafting sections, and no research beyond that. It may open the pages this one links to and its siblings in the docs tree, to see what they carry and how they name things; the reference page still sets the register. It names the judgment each section owes its reader, writes toward that rather than toward the fact list, drafts the page whole so the sections carry a through-line, and reads it back once before returning it.

Before the editor test, read the draft against the pages it links to and its siblings for overlap and contradiction. That check is the session's, which has the doc set in view; it is not a rule in the drafter's brief.

Review the whole draft, then sort the corrections by one question: does this change what a unit is for, or only what a sentence says? A fact, a label, a link, a number, or a word: edit it directly. A sentence or paragraph reworked with its idea unchanged: rewrite that unit whole and read it back against the standard. A changed idea, a section or more, or the second round of corrections on the same unit: hand the draft, the corrections, the standard, and the reference page to a fresh drafter and run the editor test after, because by then this session holds the old framing and the discussion about it, and patches accumulate into prose written in three different contexts.

Uncertain content is left out and recorded, never hedged. Concept sections describe, task pages instruct. Frontmatter descriptions are written last, from the finished page.