care-flow-doc

name

care-flow-doc

description

Use when creating or updating a FLOW doc (the "How do I…?" task layer) for the Care docs site. Trigger when adding a walkthrough for a user task (register a patient, close an encounter, dispense a medication), when a Care UI change alters the steps of an existing task, or when the user says "write a flow for X", "document how to do X", "the steps are out of date", or "this flow is missing". Covers the quality bar (create-patient), the page structure, sourcing steps from care_fe rather than guessing, the manual flow sidebar, link/MDX conventions, the manual flow sidebar, link/MDX conventions, versioning, and build validation.

Building Care flow docs

A flow answers "How do I…?" — it walks a user through one task in the product, start to finish. It is neither a concept (what a thing is) nor a reference (what fields it has). A reader arrives at a flow with a job to do.

Flows live at flows/<domain>/<slug>.mdx under the versioned docs. Follow the shared conventions for which version to author in and how to mirror. One task per page.

A flow is strictly user-facing. Clinicians and operators read it. Never put code, file paths, class names, API endpoints, payloads, database columns or permission slugs in a flow.

The quality bar

The gold standard is the template at assets/flow-template.md. Read it every time. It defines the section names and their order, and they are not negotiable.

flows/clinical/create-patient.mdx is a worked example of the shape, but it predates the template: it uses different headings and still carries an ## API equivalent section. Where it disagrees with the template, the template wins and that page is wrong. Study how a good flow:

• Opens with one sentence naming the task and its end state ("the minimum path from search to a saved record ready for an encounter").
• Pulls the conceptual background out into a admonition linking the concept, so the steps stay uncluttered.