SmartLink Style Guide

This section offers guidance to Builders who develop new SmartLinks intended for inclusion in Connect Care standard documentation templates or for any summative documentation object.

Naming Conventions

SmartLinks have five identifying fields that should be used consistently while following AHS design standards. Following these guides will make it easier for builders and analysts to find new SmartLinks for validation and easier for users to search for SmartLinks to pull into their SmartPhrases or notes.

  • Name

    • All Connect Care SmartLinks should be named in compliance with design standards.

    • Must start with "AHS ".

    • Next indicate the context (e.g., "IP" for inpatient, "AMB" for ambulatory, "ED" for emergency, "ALL" for multi-context).

    • Next indicate the kind of information to be returned (e.g., "MEDS", "MEDSREC", "ID").

    • Next indicate the specific content returned (e.g., "LONG TERM", "HOME").

    • Next indicate the formatting norm (e.g., "PROSE", "RICH").

    • Example: "AHS AMB MEDS LIST LONG TERM PROSE"

  • Mnemonic

    • This identifier is what follows a "." when composing notes or is placed between "@"s when putting tokens in edited SmartPhrases.

    • Keep as short as possible.

    • Start the Mnemonic with letters reflecting how users might seek the object (e.g., "MEDLIST" for medication list, "MEDREC" for medication reconciliation).

    • Next, optionally, add a few letters to indicate the context (e.g., "HM" for home, "OP" for outpatient, "IP" for inpatient, "ED" for emergency).

    • Follow with additional letters reflecting the variant of the object (e.g., "G" for grouped).

    • The final letter can indicate whether the SmartLink will return prose-optimized ("P") or rich text ("R") content.

    • Examples:

      • "MEDLISTHMP" - home (preadmission) medications returned in prose-friendly format

      • "MEDLISTOPR" - outpatient medications returned in rich-text format

  • Short Description

    • Keep this to a phrase or very short sentence, noting that this will appear in look-up and search lists that end users will see when trying to decide whether to select a particular SmartLink for use.

    • Front-load the most important concepts, noting that pick-lists often have fixed-width columns and the last part of a sentence may not immediately display to users seeking a particular SmartLink.

    • Example:

      • "Medications List - Outpatient, Listed in Prescriber-Friendly Prose"

  • Synonyms

    • One or more Synonyms can be added to increase the probability that a SmartLink will appear in a search result pick-list.

    • Use with caution, as too many synonyms makes for crowded and complex search retrievals.

    • Always add ONE synonym composed by adding "AHS" to the front of the Mnemonic. This will facilitate user searches for SmartLinks that have been validated and approved by Connect Care.

    • Example: "AHSMEDLISTOPP"

  • Description

    • The full description will not be seen by end users. Use this space to make note of any optional parameters or special considerations in the use of the SmartLink.

Prose-Friendly Returned Text

It is important for SmartLinks intended for summative clinical documentation templates (SmartText or SmartPhrase) to anticipate and comply with the style of a parent documentation object. Seek and use any configuration options for "plain text", "prose" or "unstructured text" instead of "rich text" or "html".

  • Font Weight

    • Bold font should be used to help readers appreciate the structure of documentation. Use for Headings or Subheadings. Do not use (unless not configurable using Epic tools) for things like abnormal findings or other types of within-text emphasis.

  • Font Colour

    • Note that Summative documents are often transferred to other health information systems (e.g., Netcare, Community EMRs) using a pdf or other text container that renders all text to black and white or grey-scale.

    • Different font colours should not be used to give emphasis within-text or to indicate document structure (e.g., subheadings).

  • Font Italics

    • These can be used to draw attention to text within prose objects.

  • Font Face and Size

    • Never vary from the Connect Care standard font (Segoe UI) and point-size (11).