1. Style Guide: PROMIS User Guide
This style sheet describes style issues found in the “PROMIS User Guide” and makes
recommendations for changes to be made throughout. For items not covered in this style guide,
see the PHSA Style Guide (available at
http://pod/phsa/corpsvcs/comm/Documents/PHSA%20style%20guide%20-
%20Jan%202016.pdf), the Microsoft Manual of Style, Fourth Edition (MMoS, v4) and the
Chicago Manual of Style, Sixteenth Edition (CMoS, v16).
Prepared by J. Hall 1 21 June 2016
A
Abbreviations Use two-letter province and territory abbreviations without periods. For
example, write “BC”, not “B.C.”
Actual Use actual with care. If for example, you’re referring to an “actual” date,
consider what a “non actual” date connotes. Perhaps “current date” is a
better choice.
Ampersand (&) Use only in a company name (“Smith & Wesson”); otherwise spell out
(“Issues and Interventions”).
Appear Word usage – “Appear” - Use “appear”, not “open” or “display”, to describe
the appearance of a new screen or window.
Audience The audience is the target readers of the User Guide. Before writing
procedures (step-by-step instructions) consider what the audience needs for
context. What is it? Why do they need to know? When do they need to
know? Where is it applicable? After these questions are addressed (in an
introductory paragraph), describing how to do it makes a lot more sense.
Auto-populate Do not use as an intransitive verb (a verb with no object). If used to describe
the system automatically filling an empty field with data, indicate what is
being auto-populated. For example: Not, “The Physician’s Name auto-
populates.”, but “The system auto-populates the Physician’s Name field.”
B
Button The PROMIS User Guide uses two terms to refer to buttons. Use the
following criteria to distinguish them and then follow the Microsoft Manual of
Style guidance beyond that.
Button - Use button to describe anything clicked by a user
Icon – Use icon to describe a graphic representation of an object that a
user can click and open, but rather than “Click on the icon to expand
your search” write “Click to expand your search”.
Use bold text to show buttons that contain text and an image for button that
have an image.
2. Style Sheet: PROMIS User Guide “C” to “D”
Prepared by J. Hall 2 21 June 2016
In general, refer to a button only by its label without using the word button. If
you need to use the word button with the label for clarity, button is
lowercase. –MMMoS, page 258.
C
Capitalization Aim for a down style (lower case) as much as possible; only capitalize
proper nouns. Items identified on a user interface are generally considered
to be proper nouns, although the rule is to use the same capitalization as
the interface. When referring to items that are not proper nouns, but have
the same spelling as identified screen items that are proper nouns, do not
capitalize. Example: “You can navigate through the Patient List screen and
create your own patient list.”
Capitalization In headings (that are capitalized), do not capitalize articles and prepositions.
For a complete list of heading style, see the PROMIS User Guide template.
Capture Avoid using “capture” to describe information entered by a user (use “enter”)
or information previously entered (use “display”).
Choose Use to describe the act of deciding which option to pick from a list. Never
use “Pick” and reserve “Select” only for the act of highlighting text on a
screen to copy, or to describe something previously chosen in which calling
it chosen sounds a little religious, as in “the chosen patient”.
Click Use for commands, command buttons, options buttons, and options in a list,
gallery, or palette.
Select and clear: Use check boxes.
Remove the checkmark: Use for checked and unchecked commands.
Type or select: Use to refer to an item (as in a combo box) that the user
can either type or select in the accompanying text box. You can use enter
instead if there is no possibility of confusion.
Colon Use a colon following an introductory clause that introduces a procedure
(steps). Always capitalize the first word following a colon.
Comma Use the serial (Oxford) comma (“oranges, apples, and pears” rather than
“oranges, apples and pears”).
D
Database When referring to PROMIS, avoid calling it “the database” or “the system”.
This is techspeak. Just call it PROMIS.
Default Do not use as a verb; adjective or noun is permissible. Not “The field
defaults to Active”, but “The default value for this field is Active”.
3. Style Sheet: PROMIS User Guide “E” to “F”
Prepared by J. Hall 3 21 June 2016
Displays Avoid – use “appears”. Avoid “displays” when used as an intransitive verb
(e.g., “the screen opens”). “Displays” can only be used as a transitive verb
in technical writing (e.g. “the screen displays all current records”). Displays
requires a direct object; appears does not. MMoS, v4.
E
e.g. Latin: exempli gratia. English: for example. Avoid foreign language
abbreviations. Use “for example”.
E-charting Electronic charting. Not a proper noun, so don’t capitalize. When used in a
heading, capitalize as E-Charting (not E-charting).
English Use Canadian English except where the software uses another form (US).
etc. Latin: et cetera. English: and so on. Avoid foreign language abbreviations.
Use “and so on”.
Explain Not “Explain”; use “describes” as in “The following section describes how
to…”
F
Faulty
predication
Avoid faulty predication. Faulty predication is a grammar rule describing a
fault in relationship (predication) between the subject and the verb in a
sentence (i.e., the two do not make logical sense together).
Example: “A waterspout is when a tornado is over water.” A waterspout is
not a time.
Be careful of “is when”, “for when”, “is where”, “is because” constructions—
they often lead to faulty predication errors. To avoid this, you usually need
to revise the sentence.
Form Only use form to indicate a clinical form a user may print out. Otherwise use
screen. Note: PROMIS is built on Oracle forms, but they are of no
consequence to end users.
Formatting -
bold
Bold. Use bold character formatting only to identify the exact text of a
named item in a procedure. Do not bold text for emphasis. Do not bold text
describing named items if you’re not describing a procedure (steps).
Formatting –
double hidden
characters
Avoid the use of double spaces after the period (that’s a holdover from
typewriters), and double page returns (the document styles should look after
those sorts of page layout issues).
Formatting -
italics
Italics. Use italics sparingly for emphasis or to identify form names, report
names, and the like.
4. Style Sheet: PROMIS User Guide “G” to “I”
Prepared by J. Hall 4 21 June 2016
Formatting -
underlining
Avoid any underlining with the exception of hyperlinks.
G
Generate Avoid such techspeak when describing a process in the software. Use
everyday words such as “run” especially for processes such as running
reports.
H
HA Health authority. Do not capitalize unless including the name of a particular
health authority. Example, “The five regional health authorities govern, plan
and deliver health care services within their geographic areas.”
Headings Heading text needs to be parallel in structure. Each heading level has its
own distinct writing and formatting style.
Headings Headings must always have intervening body text. Therefore, Heading 1
needs body text before Heading 2.
His/her Avoid using the “his/her” construction as much as possible. Prefer using
plural voice so instead of “After a patient gets a flush on his/her catheter…”,
use “After patients get a flush to their catheters…”. If that proves too
awkward, use " After a patient gets a flush on his or her catheter…”
Hit Never use “hit”. Use “click”.
Hover Don’t use “Hover”. Use “hold cursor over” or “pause over” to describe pop-
up text that appears on an interface after a pause.
Hyphen Capitalize the first letter following a hyphen according to the style in which it
is placed. For example, “X-ray” is does not take a capital following the
hyphen in body text (or any non heading style), but when used in a heading,
use “X-Ray”.
I
i.e. Latin: id est. English: that is. Avoid foreign language abbreviations. Use
“that is”.
Icon See Button.
Images Images are inserted in line with text and use the Body Text paragraph style.
Include Use “include” only if there are other items but they’re not mentioned;
otherwise, use “consists of” or “comprises”.
5. Style Sheet: PROMIS User Guide “L” to “P”
Prepared by J. Hall 5 21 June 2016
Input Do not use as a verb. Use “Enter”.
Into “Into” versus “In to”. “Into” is a preposition and “In to” is a different part of
speech as the “to” is the prepositional participle of the infinitive verb. Use
“into” to answer the question, “into where?” Example, “To log into
PROMIS…” Use “in to” with a verb in its infinitive form; “To log in to see
your status…”
L
Lists There are two types of lists for documentation: ordered (numbered) and
unordered (bulleted). Used numbered lists for procedures (step-by-step
instructions) and bulleting lists in which the order is not important. Even with
unordered lists, follow some logical order for the items in it (and provide a
rationale). Unordered lists can appear in the same order as in the user
interface, in alphabetical order, in chronological order; but not added
randomly.
M
Measures Prefer metric measures using Canadian spellings (litre, kilometre, millilitre).
Note, abbreviate millilitre as “mL”, not “ml” (CMoS, 10.52 Abbreviations).
CMoS, 8.151, CMoS, 10.54–62. If Imperial measures are used in PROMIS
interface, include metric equivalent in parenthesis.
Medication Clinical drugs or supplements a patient takes. Don’t use interchangeably
with prescription.
Numbered lists Numbered lists suggest ordered steps or a ranking where the order is
important. Bulleted (unnumbered) lists identify individual items in no
particular order.
P
Paragraph Do not use multiple carriage returns (i.e., more than one instance of hitting
the Enter key) for layout purposes. Styles are meant to control page layout.
Likewise, do not use multiple spaces or tab returns for layout.
Prepositions Contrary to many grammar rules, it is acceptable to end a sentence with a
preposition, unless the preposition at the end is unnecessary.
Wrong: “We’ll be using the “P” environment to add these changes into.”
Right: “We’ll be adding these changes into the “P” environment.”
Prescription An order a physician writes describing medications a patient is to take.
Don’t use interchangeably with medication.
6. Style Sheet: PROMIS User Guide “S” to “T”
Prepared by J. Hall 6 21 June 2016
Press Word usage – “Press” – Don’t use “press”; use “click” for buttons and other
graphically elements in which “clicking” produces an action or “select” for
text that’s highlighted or items that must be activated before a button is
clicked.
Procedures Steps should never exceed seven. If possible, reduce the number of steps
in a procedure with sub steps or breaking the procedure into several
procedures.
PROMIS Always spell FULL CAPS. Never “Promis”.
S
Screen Use screen to generically describe the UI the user sees. Do not use page or
form (unless it’s a clinical form).
Screenshots Do not add drop shadows or other formatting to images and screenshots. If
required, use the default setting to add a border as follows:
BEFORE
AFTER
White, Background 1, Dark 35%
Screenshots Text and images should form a continuous narrative. For example, each
procedure needs to describe not only how to do something, it needs to
answer the following use case questions: What is it? why does the user
need to know? When is it applicable? Where does it fit into the scheme of
things?
Select Use “Choose” when used as a verb. Never use “Pick”. You may use “select”
as an adjective, as in “the selected patient” (to avoid the religiosity of “the
chosen patient”).
T
Tables Table headers should repeat on following pages. To do this, click the
Repeat Header Rows button on the Table>Layout ribbon.
7. Style Sheet: PROMIS User Guide “U” to “V”
Prepared by J. Hall 7 21 June 2016
Tables Use the table style called PROMIS available on the Tables ribbon.
Templates The new modules (and the revised User Guide) are now based on the
“PROMIS User Guide Template.dotx” template, a copy of which is uploaded
to SharePoint. In addition to styles it contains a section on writing
procedures (with examples).
Tense In technical documentation, the general rule is to use simple present tense
as much as possible (Microsoft Manual of Style). So, instead of “The new
module will gather information about the care that has been provided to
support patients…” it should read “The new module gathers information
about the care provided to support patients…”. Among other things, it
makes the writing much more concise.
U
UI Syntax Use the following terms to describe how to interact with UI (user interface)
controls and commands:
Use Case Writing needs an introductory sentence (use case) followed by a
prepositional intro (followed by a colon), before numbered steps. For more
information, see samples in the “PROMIS User Guide Template.dotx” on
SharePoint. For additional information on procedures, use the “Microsoft
Manual of Style” standards for documenting software procedures.
V
Versions For the PROMIS User Guide, the date, which appears at the beginning of
the Guide, serves as version control. The date updates automatically
whenever the document is saved. In SharePoint, use the month and year in
the title of archived versions. For example, PROMIS User Guide January
2015.
8. Style Sheet: PROMIS User Guide “W” to “W”
Prepared by J. Hall 8 21 June 2016
Voice Generally use active voice. For general descriptions, some passive voice is
permissible. For procedures, always use active voice.
W
Work List For “Work List” (“Worklist”, “worklist”), there is no consistency across the
different Views in PROMIS. “Work List” works better with its corresponding
“Patient List” (sensibly, there is no “Patientlist”). For this inconsistency and
other similar ones, we should use the spelling and case format found in
Patient View (regardless of the View).