Global Clinic Docsv1.0
Back to app
Docs / Product Documentation

7. Contextual Help System

The platform ships its documentation inside the product. Every screen carries a context-aware Help panel and an interactive guided walkthrough, and the same source generates the per-screen reference docs and feeds this documentation site. This section explains how it works so that product, support and content teams can rely on it and extend it.

7.1 Single source of truth

Each screen is described once as a ScreenDoc object in components/help/content/{site,auth,portal,clinic}.ts. From that one definition, four things are produced:

flowchart LR
  SRC[ScreenDoc source of truth] --> PANEL[In-app Help panel]
  SRC --> TOUR[Guided walkthrough]
  SRC --> MD[Per-screen Markdown in /docs]
  MD --> SITE[This documentation site /docs]
  SRC --> APP[Screen-level help references]

Because all of these derive from the same object, the help panel, the walkthrough, the screen reference and the docs site can never drift apart. When the UI changes, the ScreenDoc is updated in the same change, and everything regenerates together. This rule is enforced in AGENTS.md and validated by an anchor-checker script.

7.2 What every ScreenDoc contains

A ScreenDoc records the screen's key, route, area, title, tagline, the roles that can reach it, twelve documentation sections, and the ordered walkthrough steps. The twelve sections are always present and always in this order:

  1. Purpose and Business Context
  2. Screen Overview
  3. Controls and Components
  4. Field Definitions
  5. User Actions and Workflows
  6. Navigation and Relationships
  7. Business Rules and Constraints
  8. Data Dependencies
  9. Error Handling and Edge Cases
  10. User Roles and Permissions
  11. Related Features and Functionalities
  12. Flow and Screenshots (a flow diagram)

This consistent shape is what makes the help content reliable as a source for tooltips, guidance and FAQs: any one of these sections can be lifted into a help surface and stay accurate.

7.3 Context-sensitive help content

The Help panel resolves the current route to its ScreenDoc using exact-then-longest-prefix matching, so a deep link still resolves to the right screen's help. The panel updates automatically as the user navigates. From the panel a user can:

  • Read the twelve sections for the current screen.
  • See the roles that can use the screen.
  • Launch the guided walkthrough, which spotlights real UI elements step by step (4 to 7 steps per screen), auto-advancing with previous, pause and next controls.
  • Open the full documentation for the screen in this docs site (a deep link to the matching Screen Reference page), connecting the in-app help to the long-form reference.

7.4 User guidance and walkthroughs

The walkthrough is the product's hands-on guidance layer. Each step targets a real element via a stable data-tour anchor and floats a short instruction beside it. Steps are written to describe what is actually on screen, in a sensible order, so a first-time patient or clinic user can be led through the screen's primary task (for example, completing the visa checklist, or sending a quote). Walkthrough steps are part of the same ScreenDoc, so they stay in sync with the UI.

7.5 Tooltips

Inline tooltips use the same vocabulary as the Field Definitions section of each ScreenDoc. The product includes a reusable info-tip control for terse, in-context definitions (for example, what "escrow", "milestone" or "medical reference number" means at the point of use). The authoritative wording for any tooltip is the matching term in the screen's Field Definitions, so a tooltip and the full docs always agree.

7.6 FAQs

FAQs are assembled from the Purpose, Business Rules, and Error Handling sections of the relevant ScreenDocs, so they answer real questions with text that matches the product. Representative examples drawn directly from the screen content:

Visa

  • Why is the Submit application button disabled? Because not every checklist item is verified yet. The button shows how many items remain. Upload the missing documents in the Documents wallet to verify the linked items.
  • How does uploading a document unlock visa submission? A checklist item linked to a document derives its status from that document being verified. Verifying it on the Documents screen marks the item done on the Visa screen, even across navigation.
  • Does Global Clinic guarantee my visa? No. Global Clinic prepares the documentation and the invitation letter and tracks the application, but the grant decision rests with the government authority.

Payments and escrow

  • When is the hospital paid? Only as verified milestones are met (for example admission, procedure, discharge). Until then funds are held in escrow.
  • Can I get a refund? Pre-arrival cancellations are fully refundable. After defined milestones, the disclosed refund schedule applies.

Documents

  • Why was my upload rejected? It likely failed a file-type or size check. Re-upload a valid file. The linked visa item stays pending until a valid file is verified.

Clinic console

  • What does each inquiry status mean? New, quoted, accepted or declined. Prepare an itemised quote to move an inquiry to quoted.

These FAQs are generated, not hand-maintained: changing the underlying ScreenDoc updates them.

7.7 Documentation references

Every help surface can reference the long-form documentation:

  • The Help panel links to the matching Screen Reference page in this docs site.
  • Product and developer documentation are published under /docs with search, so any term a user encounters can be looked up.
  • The Screen Reference index lists all 32 documented screens grouped by area, each linking to its full reference.

7.8 How application screens reference help dynamically

Because help content is keyed by route and screen key, application screens reference it without duplicating text:

  • The Help button exists in every shell (public site, patient portal, clinic console) and always shows the current screen's help.
  • A screen can deep-link a user to a specific documentation page (for example, a "Learn how escrow works" link that opens the Payments screen reference).
  • Tooltips pull definitions from the same content, so a definition shown in-context and the same definition in the docs are identical by construction.

7.9 Keeping help current (governance)

The maintenance rule is strict and intentional: when a screen, control, field, action, permission, data dependency or navigation path changes, the matching ScreenDoc is updated in the same change set, the walkthrough steps and data-tour anchors are kept in sync, and the docs are regenerated. Two scripts protect this: an anchor-checker that asserts every walkthrough target resolves to a real element, and a generator that re-emits the per-screen Markdown. The docs site is then rebuilt from that Markdown. This is why the in-app help, the walkthroughs, the screen reference and this documentation are always consistent. See the Developer operations guide for the exact commands and the build order.