Bridge v4 Guides

Guides

How these guides work

How to read a guide, and what a guide has to satisfy before it is shared.

Reading a guide

What each part of a guide means. Every definition lives here, and nowhere else.

The deck

What a guide is, and what a reader meets before the first slide.

A guide One feature, one deck, sent as one link: a clinic receives the guides for the features it uses, and nothing else. A deck covers everything a reader does on that feature's screens, including the forms, records and tabs they open.
Name The feature's name followed by Guide — Intake Guide — so a link read in an email says what it opens.
Cover The feature's name as the display, spelled exactly as the product's navigation spells it, with one sentence under it on what the feature settles for the person who uses it.
Header On every slide: at the left, who the guide is for and what it covers — Staff · Feature guide on the cover, Staff · Intake guide after it; at the right, the Bridge mark. One slide, projected or forwarded alone, still says where it comes from.
Release The release of Bridge the guide was written for, the same on its index card and on the cover's footer line, as “Written for Bridge 4.0”. It dates the guide, not the product: once the release in use is newer, the guide is one to check against it.
Sample data The cover's footer line, after the release: every name, date and figure in the pictures is invented.
Formats The same deck presented full screen, paged through in the browser, or downloaded as a PDF or a PowerPoint file — at 16:9, legible when projected in a training session.
Index card The guide's entry in the index: its name, its side, its cover sentence and its release, opening the deck.

The slides

The slides a guide can hold, in the order a reader needs them: why, where, what they see, what they do, and what can go differently.

What it is for The job the feature does in the clinic's day, and who in the clinic does it.
Where to find it Every way to open the feature, as the reader gets there: the menu they open, or the message whose link they select. In every guide.
The screen A picture of the feature's screen with numbered markers, and one line per marker on what that part is for.
How to <task> One task the reader came to do, start to finish: a picture of the screen at that point, numbered steps, each pointing at the marker with its number, then the result.
What each status means Every status a record can show, as its badge reads, with what it means and what the reader does next.
When something goes wrong One card per message the reader may see instead of what they expected, led by an icon: what it means, and what to do about it.
What can differ in your clinic What depends on how the organisation has set Bridge up, or on what the reader's own account can do — and who to ask to change it. In every guide.

Marks on a slide

Signs a slide carries beside its content, the same in every guide.

Numbered marker A number on the picture, matching the action beside it that carries the same number. Only actions are numbered.
Result A check in an outlined circle beside the line that says what the reader sees once the task is done. It has no marker on the picture.
Patient view A screen a patient uses on their own phone or computer, shown so staff can walk a patient through it.
Speaker notes What a trainer says over the slide, kept beside it. Anyone who opens the deck can read them.

Writing a guide

What a guide has to satisfy before it is shared. None of these rules restates a definition.

Who it is for

The reader a guide is written for, and the person it is written about.

Audience The clinic's staff and providers — the people who use the feature every day, and the people who train them. A guide says what to do and what will happen, never how Bridge does it: no setting or permission by the name the code gives it, no requests to the backend, no environments. Bridge's own teams read the feature documentation instead.
Patient screens Covered as training, so staff and providers can guide a patient through them. The task is the patient's — "Book an appointment" — and the steps are written for the staff member to follow: "Your patient selects Schedule." A guide is never sent to a patient.
Their words Every control named exactly as its label reads on screen. Plain English, in the second person, one instruction per sentence.
Functional tone A guide states what to do and what happens. The clinic already has the feature, so nothing in a guide sells it.

Where it comes from

What a guide is allowed to say, and what its pictures are taken from.

Only what the doc says Every claim in a guide has a row behind it in the feature's documentation. A guide adds pictures and steps, never a fact: where the documentation has no row, the guide says nothing.
In the same change Rebuilt in the change that rewrites the feature's documentation, and reviewed by QA with it, so the two describe the same product.
The Demo wins The Portal Demo is the base. Where the documentation and the Demo disagree, the documentation is rewritten to the Demo and the guide follows it; an old capture is retaken, and the text is never bent to match it.
Captured from the demo Every picture is a capture of the demo, filled with invented data. Never from a clinic's environment, not even a test one, and never a real screen edited to hide what it held.
One deck for every clinic A guide describes the feature as the product ships it. A clinic without a part learns so from What can differ in your clinic, never from a copy of the deck edited for it.
Captures, not drawings A screen is shown as it renders. A drawing of it drifts from the product the day either one changes, and nothing reports it.

Where each slide comes from

How the parts of a feature's documentation become slides.

What it is for The documentation's lede, turned to the person who does the job.
Where to find it The navigation routes and the links of the Access card, as the reader takes them. The app, the path and the host stay out: the reader never types them.
The screen The parts from Header to Table: one marker for each part the reader has to recognise to work the screen.
How to <task> The main actions and the row actions the reader starts on purpose, with the form, record or workspace each one opens. A form's validations become what it asks for and what it refuses, in words.
What each status means The status rows, in full.
When something goes wrong The Errors card, from what the reader gets. An error the product still shows as the generic one stays out: the guide cannot tell the reader what it means.
What can differ in your clinic The permissions cells, in words. An organisation setting becomes "If your organisation uses …"; a permission on the account becomes "If your account can … — your administrator decides"; a condition on the record becomes the condition itself — "Only for visits that have not started".
Left in the doc The API calls card, and every key, code and path.

Self-contained

A guide, and every slide in it, holds up when anything else changes.

No links Nothing in a guide points anywhere. A deck travels alone — sent to one clinic, downloaded, projected — where a link cannot be followed or opens something the reader has not been given.
Every slide stands alone A trainer shows slides out of order, and a reader jumps to the one task they need, so no slide says "as before", "next" or "see the previous slide".
No borrowed explanations A guide never explains its feature through another feature's behaviour. Another feature is named only where the reader has to go there, spelled as the product's navigation spells it.
Meaning, not contents A title or a lede says what the reader can do, never how much there is: no counts of steps, statuses or slides. "Check a patient in" holds when a step is added; "Three steps to check in" does not.
One lede, everywhere The cover sentence is written once, and the guide's index card repeats it word for word, so a guide and its listing cannot disagree.

What a slide says

How a single slide is filled, whatever kind it is.

Title and intro Every slide after the cover opens with its title and one line on what the slide is for, never on what it holds.
Task titles The reader's goal as a verb phrase in sentence case — "Check a patient in" — never the name of the control that starts it.
One task, one slide A task too long for one slide is split where the reader has something finished, and each half becomes a task with its own title.
Steps Each opens with the verb and the control: "Select Check in." Select, never click or tap — the same guide serves a mouse, a touch screen and a keyboard.
The result The line under the steps says what the reader sees when it worked — the row that moves, the badge that changes — marked as the result and never numbered, so every number has its marker on the picture. It comes last: anything the reader can do once it worked — going back, undoing it — is a plain line under it, never another step.
Statuses The whole set, in the product's words, each as the pill it wears in the product, never only the ones a picture happens to show.
Differences in one place What depends on the organisation or the account is said on What can differ in your clinic and nowhere else; every other slide shows the feature as the product ships it.
Speaker notes Drawn from the same rows as the slide they sit beside, in the words a trainer would say. Everyone who opens the deck reads them, so they hold nothing a clinic should not see.
Errors The message as it reads on screen, what it means for the reader's work, and what to do next. Failures every screen shares — a dropped connection, an ended session — are left out.

What a guide leaves to the system

The boundary between a guide and the design system.

States Loading, empty and no results look the same on every screen, so no guide gives them a slide. A picture shows the screen loaded and holding records.
Built from the system Every slide is composed by the design system's Decks section, from the deck tokens installed in the deck, on the system's deck backdrops. A guide that invents its own values has already drifted from the product it pictures.

Order and absence

Where slides sit, and what a guide says when a slide has nothing to hold.

Slides In the order the slide kinds are defined here. A reader who has used one guide finds the same slide in any other by position.
Tasks In the order the reader meets the control that starts them: top to bottom, then left to right. A task started from inside a form, record or workspace follows the task that opens it.
Statuses In the order a record moves through them, never alphabetically.
The same, twice No slide is ordered by preference. The same feature written twice produces the same guide twice, so a change to a guide is always a change to the product.
Slides a feature does not need Skipped — a feature whose records carry no status has no status slide. The order of the rest does not change.
Slides that are always there Where to find it, and What can differ in your clinic. A reader cannot tell "the same everywhere" from "not written", so when nothing differs the slide says so in one sentence — "This works the same in every clinic."