Style Guide
Formatting and style guidelines for Forge product copy
Introduction
This page covers style and formatting for Forge product copy. Consistent structure, usage, capitalization, and punctuation all help create a familiar, focused user experience. It helps answer questions like “What kind of list should I use?” and “Do I need a comma here?” It doesn’t cover our principles, our product personality, or what your copy should say; you can find this information on the Content page.
Key takeaways
- Fundamentals like brand, capitalization, punctuation, and formatting help create familiarity and predictability, so users can keep their focus on what matters.
- UI elements have additional copy guidance that enhances their usability.
- Some usages and terms feel about the same, but it’s worth knowing when to use each one.
- Consult the word list for athenahealth-specific terms.
Fundamentals
Brand
Use lowercase for company and product names, even at the beginning of a sentence. For additional information, visit athenahealth’s brand site.
Company
Use:
- athenahealth to refer to athenahealth employees or the company as a whole: “athenahealth calls payers on your behalf.”
- athenaOne to refer to the application and automated actions: “athenaOne flags claims for followup.”
- athenahealth, Inc. only when referring to the company as a legal entity (for example, in legal documents).
Don’t use:
- athena externally or in product copy. athena is informal and imprecise, so it’s best for internal use only.
- athenaNet. athenaOne replaced athenaNet in July 2022.
- aOne externally or in product copy. Use the full application name athenaOne instead.
Products
Use the full product, service, and feature name:
- athenaCollector, not Collector (and similar for other athenahealth products)
- The Patient Portal, not the portal
- athenaOne Medical Coding, not the medical coding service
Voice and tone
Active voice
Use the active voice for clear, direct product copy that helps users complete tasks. The active voice:
- Makes clear who is performing an action
- Uses a simple structure
- Often uses fewer words
Do this | Not this |
---|---|
“You must attest by December 31, 2022.” | “Attestation must be submitted by December 31, 2022.” |
Customers, clients, users
Customers are organizations and end users who use athenahealth products and services. (Clients is no longer the preferred term.)
Users are individuals who use our products and services. Where possible, use:
- You to address users directly
- More descriptive terms to refer to specific groups of users, like clinicians and staff
We, you
Use we in product copy only:
- When we refers to athenahealth employees performing an action: “We can create a custom interface for your practice.”
- In patient-facing applications like the Patient Portal, where we refers to the practice: “We look forward to seeing you at your appointment on December 3, 2022.”
When addressing users:
- Use you in body text, introductions, and other descriptive copy: “Before you begin, find the 5-digit authorization code. You’ll need to enter this during the certification process.”
- Use the imperative voice to avoid you in instructions: “Enter the patient’s name and address”, not “You need to enter the patient’s name and address”
Pronouns
Instead of defaulting to a gender, use terms that can apply to any gender. When speaking generally, use they for both plural and singular.
Courtesy words
Courtesy words like please, thank you, and sorry can distract users from important information. Use them sparingly.
Do | Don’t |
---|---|
Use courtesy words for serious problems, significant delays and inconveniences:
| Use them for ordinary instructions, short waits, or minor inconveniences:
|
In addition, use thank you when users have done something that benefits athenahealth, such as submitting feedback, a bug report, or data that we requested.
Can, might, may
Use | To indicate | Example |
---|---|---|
Can | Ability | “You can attach additional documentation and resubmit the claim.” |
Might | Possibility | “Patients might prefer to complete the survey online.” |
May | Likelihood | “Patients may be eligible for additional coverage at age 65.” |
May | Permission or authorization | “Approved vendors may attend the event.” |
Capitalization
Forge uses a combination of sentence case and title case, depending on context.
Sentence case
Capitalize the first word and proper nouns: “First and last name”, “Other locations in Massachusetts”
Title case
Capitalize the first and last words. Capitalize all other words except:
- Prepositions such as in, out, of, with, without, about, around, near
- Articles such as a, an, the
- Conjunctions such as and, or, but
For example:
- “Delete Patient Record”
- “Date of Service”
Phrasal verbs
Phrasal verbs consist of two words that are treated as a single unit. When using title case for a phrasal verb, capitalize both words (even though the second word is often a preposition):
- “Log In to athenaOne”
- “Back Up Now”
Other common phrasal verbs that follow this pattern include:
- Check In
- Check Out
- Look Up
- Set Up
- Shut Down
Hyphenated words
When a title includes hyphenated words, capitalize the first and last words. Capitalize additional words, unless they are articles, prepositions, or coordinating conjunctions (and, but, for, or, nor).
- “In-Depth Coverage”
- “Step-by-Step Instructions”
Need help? Try this title case converter.
Exceptions
Some use cases call for a more conversational tone. It’s OK to use sentence case if title case makes the copy look awkward:
- Button copy: “Yes, this is my doctor”, not “Yes, This Is My Doctor”
Acronyms and initialisms
Spell out the full name the first time it appears in body copy, followed by the acronym or initialism in parentheses. Don’t use a period after each letter.
- “One product is an electronic health record (EHR).”
Tall man lettering
Tall man lettering helps users differentiate between drugs that have similar names:
- DOBUTamine, DOPamine
- buPROPion, buSPIRone
- predniSONE, predniSOLONE
Some athenahealth products may use specific formats for medication names. Ask your PO whether this applies to your work.
All caps
Avoid all caps: it’s hard to read and can be interpreted as shouting.
Examples
Element | Case | Example |
---|---|---|
Button | Title case Exception: Sentence case is OK for conversational tone where title case would look awkward | “Save and Add Insurance” Exception example: “Yes, book this appointment” |
Dropdown list item | Sentence case | “Patient’s father” |
Field label | Sentence case | “Last name” |
File extension | Lower case | “.pdf” |
File type | Uppercase | “PDF” |
Headings:
| Title case | “Patient Registration” |
Hint text | Sentence case | “Last name can include spaces, hyphens, and apostrophes” |
Placeholder text | Sentence case | “- Type or select a patient name -” |
Hover text, tooltip text | Sentence case | “Indicates custom settings” |
Icon label | Title case | “Add Note” |
Job title | Lowercase | “nurse practitioner” |
Link | Sentence case | “Learn more” |
Tab labels | Title case | “Provider Info” |
Table:
| Title case | “Task Status” |
Table:
| Sentence case | “Waiting on payer” |
Tags | Title case Note: Tag copy may be displayed in all caps or small caps using CSS, but the copy itself should be in title case, not all caps. | “In Process” |
Punctuation
Period
End all sentences with a period. Use one space (not two) between a period and the next sentence.
Don’t use periods in titles, headings, or subheadings.
Comma
Use the serial or Oxford comma. This means including a comma before and in a list of 3 or more items: “The patient care team consists of doctors, nurses, medical assistants, and other providers.”
In addition:
- Use a comma between a name and degree: “Lesley Clark, MD”
- Use a comma after the date when a date includes the month, date, and year: “January 4, 2023”
- Don’t use a comma between just a month and year: “January 2023”
- Use a comma after e.g. and i.e.: “Use this form to order office supplies (e.g., paper, pens, staplers).”
Ellipsis
Use an ellipsis (…) to indicate:
- Truncated text: “hyperli...” when “hyperlimidemia” is cut off in a small space, like a table cell
- Hidden content: “CT reveals no evidence of dis... (see more)” in a ShowHide
- An incomplete process: “Loading claims...”
To prevent line breaks in the middle of an ellipsis, render it as the single HTML character …
or …
.
Ampersand
Spell out the word and in most instances.
When space is limited, and the two words are conceptually connected, an ampersand (&) can be used instead: “Assessment & Plan”, “A&P”
Exclamation point
Use rarely in UX copy. To convey urgent or important information to users, rely instead on a combination of design elements, like icons, color, alert types, and interruption components.
Lists
Numbered, bulleted
Use a numbered list if the order of the items is important (for example, a prioritized list or step-by-step instructions). Otherwise, use a bulleted list.
Writing lists
- State one idea or data point per list item.
- Use the same structure for all list items:
- Make all list items either phrases or complete sentences.
- Start all list items with same part of speech (nouns, verbs, articles, etc.).
- Use the same tense for any verbs.
- Be concise: short list items are easier to scan.
- Use sentence case.
Punctuation in lists
- Introduce lists with a colon.
- Use periods consistently:
- Use periods if all list items are complete sentences.
- Don’t use periods if all list items are phrases.
- Don’t use commas, semicolons, or conjunctions (and, or) at the end of list items.
Do this | Not this |
---|---|
“Activities of daily living include:
| “Activities of daily living include
|
Formatting
Numbers
Use numerals for all numbers, including those between 1 and 10. Numerals are easier to scan, and they can help make copy shorter.
Exception: It’s OK to spell out one in copy like “Choose one of the following”.
Additional points:
- Use a space between numbers and units: “300 KB”
- Use a comma in any number over 999: “$1,024”
Some athenahealth products use specific number formats for patient safety reasons. Ask your PO whether this applies to your work. For example, some applications might:
- Include leading zeroes: “0.5”, not “.5”
- Exclude trailing zeroes: “10”, not “10.0”
Dates
Forge’s standard date format is MM-DD-YYYY. When a shorter format is necessary due to space constraints, use MM-DD-YY.
When writing out the date in body text, spell out the month when possible. When abbreviations are necessary, use Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec (no period at the end).
Days
Spell out days of the week when possible. When abbreviations are necessary due to space constraints, use Mon, Tue, Wed, Thu, Fri, Sat, Sun (no period at the end).
Time
Forge’s standard time format is HH:MM, followed by AM or PM and the time zone abbreviation: “10:30 AM EST”
Phone numbers
Forge’s phone number format is (###) ###-####.
Medications
For clarity and patient safety reasons, some athenahealth products may use specific formats, like tall man lettering, for medication names. Ask your PO which format your product uses.
Bold
Use bold text sparingly to emphasize key words or phrases:
- A bold word or phrase can help focus users’ attention.
- Bolding an entire sentence reduces readability and is less effective as emphasis.
- Don’t bold whole paragraphs.
Use bold text in specific instructions that refer to UI elements, like buttons or links:
- “2. Enter your password and click Log In.”
Don’t use bold text for UI elements in descriptive or conceptual body text:
- “The Insurances section displays information about the patient’s primary and supplemental insurance policies, including prescription drug coverage and insurance card images. Verify all information with patients when they check in.”
Bold text should be the same color as the surrounding regular text. Don’t use a different color for additional emphasis, because different color text often indicates a link.
Italic
Use italic text only to introduce new terms (usually followed by a definition or explanation in regular text). Italic text can be hard to read, so use it sparingly.
Product and UI
The fundamentals apply broadly to interface copy, but some UI elements have additional guidelines that help create a consistent user experience across products.
Interaction
Buttons
Start Button text with a verb. Keep it as short as possible. Use title case.
- “Save”, “Confirm Appointment”, “Go Back”
For help writing:
- Button copy, see Content
- About buttons (for example, in instructions), see Referring to UI
Links
Link text should clearly indicate the destination or action (for tertiary Buttons). Use sentence case.
- “View profile”, not “Click here to view profile”
For help writing about links (for example, in instructions), see Referring to UI.
Filtering and searching
A filter helps users narrow down information displayed on a page.
- Label: “Filter by”
- Button: “Filter”
- Tertiary button: “Reset”
A lookup enables users to enter search criteria to find information that isn’t displayed on a page.
- Label: “[Item] Lookup”
- Button: “Find”
- Tertiary button: “Reset”
Notification
Alerts
Alerts are temporary messages that appear under certain conditions.
Use alerts to:
- Call attention to a change or specific information
- Encourage or require users to take action
Don’t use alerts to:
- Emphasize or stylize static page copy
Forge has four alert types:
Name | Color | Description | Usage | Example |
---|---|---|---|---|
Info |
| General tips and helpful information that might not require user action | Health insights, an explanation of a Medicare abbreviation | “PCMH stands for Patient-Centered Medical Home.” |
Success |
| A confirmation message when a task or action has been completed | Action completed, content saved | “Your selections have been saved.” |
Attention |
| An error or alert that the user should be aware of, typically requiring user action | Missing required fields, mild clinical warnings | “Screening overdue” |
Critical |
| Reserved for the highest risk and most severe issues, like patient safety or a business problem that could affect the customer’s financial health | Moderate or severe clinical warnings, a financial issue that would result in lost Medicare payments | “Conflict with patient allergy: ASPIRIN” |
For more information, see:
Errors
Error messages should indicate what happened and how users can fix the error. Be clear, concise, and specific. Use sentence case.
- “Enter an email address that matches the format person@domain.com”, not “Invalid email address”
Form validation errors usually occur when users enter information that’s incomplete or doesn’t match the expected format. Inline error messaging can help users locate the issue quickly and resolve it.
- “This discount code has expired. Enter an active discount code.”
If users might miss an inline error message because of where it appears on the page (for instance, if they have to scroll to see it), include an additional error message at the top of the page.
- Top of page: “You must complete all required fields.”
- Inline: “Enter the last name.”
For help writing error messages, see Content.
Input
Form field labels
Use nouns, not verbs: “First name”, not “Enter first name”
Use sentence case: “Date of service”, not “Date Of Service”
Don’t use colons (:): “Phone number”, not “Phone number:”
Don’t skip form field labels and just use placeholder text instead, because:
- When users click in an input field, the placeholder text disappears. If users are interrupted and come back to continue what they were doing, they might not remember what to enter in the field.
- Screen readers use labels to announce fields.
Dropdown lists
The default placeholder text for:
- Select is “- Select -”
- SingleSelect is “- Type or Select -”, but you can change this to reflect the content of your list: “- Type or select patient name -”
- Multiselect is “- Type or Select -”, but you can change this to reflect the content of your list: “- Type or select payers -”
For help writing about dropdown lists (for example, in instructions), see Referring to UI.
Display
Page and section titles
Page and section titles orient users, trainers, and technical writers in the application, so it’s important for titles to be clear and specific.
Start athenaOne pages with a title near the top. These titles should be descriptive and unique, so that:
- Users can refer to the page title to describe where they are in the application: “I’m on the Review Medications page.”
- The page is distinct from any other, similar pages: “Edit Deposit Batch” and “Edit Payment Batch”, not just “Edit Batch”
If a page is just a container for several sections or widgets, these items can have their own titles instead: “I’m looking at the My Messages section, on the right.”
Referring to UI
When writing about UI elements (for example, in instructions):
- Bold the element name.
- Don’t use quotes.
- Avoid using the term for the UI element (button, link, tab, heading, etc.).
When instructions include using buttons or links:
- Use click.
- Don’t use click on, press, or hit.
- For mobile and touch screen applications, use tap.
When referring to dropdown lists (like Select, SingleSelect, or Multiselect):
- Use list or menu: “Select a provider in the list.”
- Don’t use dropdown.
Key terms
Some words have specific meanings in healthcare and in athenahealth products. Check the O-help glossary to make sure you’re using a term correctly.
Before you name a new feature or option, confirm that athenahealth isn’t already using the term for something else. Using the same name for different features can confuse users who use multiple athenahealth products and services. For help with product naming, email the athenahealth brand team at brand@athenahealth.com.
Usage
Continue, next
Use continue for sequential steps in a workflow (e.g., moving through multiple steps to set up an account).
Use next for non-sequential items (e.g., moving from one claim to another).
e.g., i.e.
e.g. and i.e. are often confused but are not interchangeable:
- e.g. means “for example” (from the Latin exempli gratia).
- i.e. means “that is” (from the Latin id est).
Use a period after each letter. Follow the abbreviation with a comma.
Fewer, less
Use fewer for items that can be counted: “fewer patients”, “fewer diagnoses”, “fewer columns”
Use less for items that can’t be counted: “less water”, “less time”, “less stress”
Log in, login
Log in is 2 words when used as a verb: “Users can log in on their mobile device.”
- If using to, keep in and to separate: “Log in to athenaOne”, not “Log into athenaOne”
- When using title case, capitalize both words: “Log In Now”, not “Log in Now”
Login is 1 word when used as a noun or adjective. This usage refers to access credentials:
- Noun: “Set up your login.”
- Adjective: “Follow the login instructions.”
Plural, singular
If an item can be singular or plural depending on the context, use the plural. Don’t use (s) to cover the possibility of both singular and plural items: “Lab results”, not “Lab result(s)”
Column headings should be:
- Singular if each cell can contain only one piece of information: “Denial Reason” for one reason per row
- Plural if each cell can contain multiple pieces of information: “Denial Reasons” for multiple reasons per row
View, show
Use view when the user’s context will change (for example, a Modal or a new page will open): “View test results”, “View history”
Use show when the user’s display on the current page will change (for example, additional details or list items will appear):
When | Do this | Example |
---|---|---|
More detail will be displayed | Use a show/hide toggle | “Show notes / Hide notes” |
More items will be displayed | Use a more/fewer toggle If quantity is relevant, include a numerical indicator in parentheses. | “Show more / Show fewer” “Show more (10) / Show fewer” |
All items will be displayed | Use an all/fewer toggle If quantity is relevant, include the total number of items in parentheses. | “Show all / Show fewer” “Show all (18) / Show fewer” |
It’s not clear what will be displayed, or multiple types of information will be displayed on the same page | Include a noun in the toggle | “Show all results / Show fewer results” |
Truncated text will expand to display the remaining text | End the truncated text with an ellipsis (…) and a space, followed but a more/less toggle | “... Show more / Show less” |
Word list, A-F
A
athenaClinicals
athenaCollector
athenaCommunicator
athenaCoordinator
athenaCoordinator Enterprise
athenaFax
athenahealth
athena.intelligence
athenaNetwork
athenaOne (use instead of “athenaNet”, effective July 2022)
athenaOne Medical Coding
athenaTelehealth
B
backup (n)
back up (v)
briefing (use instead of “facesheet” in athenaClinicals)
C
cancel, canceled, canceling, cancellation
center (not “centre”)
check-in (n) (capitalized as “Check-in” when referring to the 5-stage patient encounter)
check in (v)
checkout (n)
check out (v)
claim note
claim rule
Customer Support Center (not “CSC”)
copay (not “co-pay”)
coinsurance
cover sheet
D
dialog box (not “dialogue box”)
download (n, v)
Down syndrome
E
EHR (electronic health record; use this instead of “EMR” or “electronic medical record”)
email (n, v)
F
FAQ (not “FAQs”)
follow up (v)
follow-up (n, adj)
full-time
full service (adj)
Word list, G-R
G
.gif (lowercase in a file name: “photo.gif”)
GIF (all caps as an acronym)
GB (gigabyte, or 1,000,000,000 bytes)
go-live (n)
go live (v)
gray (not “grey”)
H
healthcare
HIPAA (not “HIPPA”)
homepage
I
insured
internet
intranet
J
Java
JavaScript
K
KB (kilobyte, or 1000 bytes)
Kb (kilobit, or 1000 bits)
kick code
kick reason
kickoff
L
lab work
license (n,v; not “licence”)
lockbox
login (n)
log in (v; use this instead of “sign in” for entering username and password)
log out (v; use this instead of “sign out” for ending athenaOne session)
M
Mb (megabit, or 1,000,000 bits)
Mb/s (megabits per second)
MB (megabyte, or 1,000,000 bytes)
MB/s (megabytes per second)
menu bar
N
Nonpatient
O
O-help
offline
OK (all caps)
P
payer (not “payor”)
pop-up window
preventive (not “preventative”)
Q
quickpick
Quickview (capitalized athenaOne page title)
R
real time (n)
real-time (adj)
Word list, S-Z
S
Social Security number (first two words are capitalized; last word is not)
setup (n)
set up (v)
sign in (v; use “log in” instead for entering username and password)
sign off (v; use “log out” instead for ending athenaOne session)
sign-off (n)
signup (n)
sign up (v)
smartphone
specialty (not “speciality”)
startup (n)
start-up (adj)
Success Community
T
take-back (n)
take back (v)
Task Bar
toolbar
U
undelete
upload
username
V
voicemail
W
web
website
web page
worklist
Workspace
Z
ZIP code (not “Zip code”)
Resources
- Chicago Manual of Style: https://www.chicagomanualofstyle.org/book/ed17/frontmatter/toc.html
- Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
- athenahealth brand voice guidelines: https://brand.athenahealth.com/guidelines/brand-voice
- Merriam-Webster online dictionary: https://www.merriam-webster.com/
- Show Numbers as Numerals When Writing for Online Readers: https://www.nngroup.com/articles/web-writing-show-numbers-as-numerals/
- FDA Name Differentiation Project: https://www.fda.gov/drugs/medication-errors-related-cder-regulated-drug-products/fda-name-differentiation-project
- Look-Alike Drug Names with Recommended Tall Man Letters: https://www.ismp.org/recommendations/tall-man-letters-list