Content
Follow these guidelines for writing microcontent (short text fragments or phrases, i.e. headlines, links, email subjects, or labels) and UI copy (commands and actions). These guidelines serve as a foundation for Watermark’s tone of voice and formatting rules.
Summary
Write content with a tone that is respectful, sincere, formal but friendly, and matter of fact but warm, while using plain language that is concise and easy for your users to understand. Use the active voice when the actor of the action is important, and the passive voice if the event or action is more important. Ensure content is formatted properly and lead with verbs for actions and commands.
Know Your Users
Before you begin writing, it is important to understand who you are writing for and how your audience will use your content.
Administrators
Admins are extensively using our tool for a variety of complicated processes and tasks that require setting up the system for others to use. Be sure to communicate their progress and system status along the way. We also need to ensure they have a proper understanding of data objects, definitions, and workflows that will help them set their staff, faculty, and students up for success.
Faculty/Contributors
Faculty or Contributors are here to complete tasks and use our system for only part of their overall responsibilities. Oftentimes assessment and accreditation processes carry a stigma and are potentially an afterthought in the context of their teaching or research responsibilities. Guide them to seamlessly complete their assigned activities.
System Administrators/IT
System Admins are here to manage their institution’s data and troubleshoot. They want to get straight to the point, so speak plainly and don’t be afraid to spell it out. Be sure to directly and effectively communicate that their actions can have serious consequences that impact data, access, and the security of their institution’s products.
Students
Students are exclusively focused on completing their program and tracking their status. They may be required to enter data for assessments, field experience, or any other program-required activity. Students interact with our products only briefly to complete these activities or reach out for help and may feel overwhelmed, so we need to be direct and easy to understand while remaining friendly to keep them engaged.
Tone of Voice
Tone of voice influences friendliness, trustworthiness, and desirability.
We use language that is respectful and serious with writing that is clear and easy to understand, while remaining human with a tone that is halfway between formal and casual. It is also important to convey our expertise in higher education with language that is matter of fact and enthusiastic.
Formal & Casual (Think Business Casual)
Communicate with proper etiquette while remaining relaxed to convey that we are friendly and trustworthy.
Serious
Speak sincerely to our users to convey our respect and admiration of higher education.
Respectful
Convey our appreciation for our users to maintain their trust.
Matter of Fact & Enthusiastic
Use language that is factual and distinct from opinion to show that we are informed, but remain warm with an optimistic tone.
Use collaborative and conversational language to stay engaging, instead of dictatorial and arrogant language which can come across as irreverent. Our tone is not disrespectful or funny. Stray away from coming across as too formal to remain relatable, and too casual or too enthusiastic to remain respectful.
Examples
Correct Use
“Use this section to include cover pages, introductory statements, and more. The pages that you add here will be the first pages of your self-study.”
“Document achievements as you make your way through your academic journey.”
“Submit a work request to apply changes to your system.”
Incorrect Use
“Just so you know, this section includes cover pages, intro statements, and more. Pages you add will be the first pages of your study!” Too Casual
“Congrats on your academic journey! Here you can document your achievements. Feels pretty great, doesn’t it.” Too Enthusiastic & Funny
“If you are ready to apply a change to your system, submit a work request defining the pertinent revisions.” Too Formal
These guidelines can be tailored slightly to better fit the needs of different personas. For students we can try to be more enthusiastic and casual, as this is more likely to keep them interested. You may find being more formal works better for higher up members of institutions such as the president or dean. Use these guidelines as a guide but use your better judgement when it comes to keeping your users engaged.
Use Plain Language
Users scan and read very little (averaging only 20% of content), so content needs to be concise, easy to consume and understand.
Do
-
Use familiar words, be concise, and focus on the main point
Ask, “What do they need to know,” “Is there a way to make this shorter?”
-
Write positively
Look out for words like “can’t” and “don’t.”
-
Be cognizant of using please and sorry
These words are overused and don’t have the same connotation across cultures.
Use please if we’re asking the user to do something inconvenient or if the system is at fault. It can also be used in error messaging.
Use sorry in situations where the user faces a serious issue i.e. data loss, needs to contact Watermark support.
Avoid
-
Avoid idioms, cliches, slang and jargon
Jargon is technical language that not all users will understand. This also include acronyms or abbreviations. If the term or acronym is important, pair it with plain language, define it in context, or give examples.
For mostly non-experts, first use the plain term and add the technical term in parentheses: “collection of related programs (Meta-majors)”
For mostly experts who would most likely know the technical term, you can use the technical term first and add the plain term in parentheses for any non-experts to understand: “Meta-majors (collection of related programs)”
-
Avoid long or run-on sentences
Be concise and remove word bloat, “really, very, great.”
-
Avoid referring to the location of items on the page
For accessibility reasons, don’t use directional words like “above, below, to the left.” Content can be scaled and moved based on screen size, so directional language isn't always accurate. For example, instead of using “Complete the field above,” try to describe the action more, “Complete the description field.”
-
Avoid Contractions
Avoid shortening words, i.e. “can’t,” “don’t” so that we remain respectful, matter of fact, and serious.
Grammar
Follow these guidelines to apply the correct voice and tense when writing content.
Active Voice
Primarily use the active voice when the subject of the sentence is performing the action in the present tense, i.e. “The dog is chasing the ball.” The present tense is where an action or state is currently going on. This voice is considered more concise and direct, making it easier to understand for non-native speakers.
Correct use
“Casey Coachman has approved your submission.” Casey is the subject performing the action.
“Please enter your name in this field.” You are the subject performing the action.
“Track your progress towards project completion.” You are the subject performing the action.
Passive Voice
Use the passive voice to put emphasis on the action or event, rather than the person or thing responsible for the action. In other words, the focus is on the action being done to the subject, rather than the subject doing the action.
Correct use
“Your submission has been approved.”
“The plan is closed for editing.” or “The plan has been closed for editing.”
Your “submission being approved” and the “plan being closed” is the event. We do not need to know who performed the action.
Incorrect use
“Project completion can be tracked by you.”
“This field is to be completed.”
We do not need to indicate that “you” are recieving the action. These sentences should be rewritten in the active voice, i.e. “Complete this field,” “Track project completion.”
Understand how to use the different types of perspectives.
2nd Person
Primarily use 2nd person. This means using “your” instead of “my,” i.e. “Create and monitor program reviews for your institution.” This helps to reinforce a more human and personal tone, like the product is working for you and walking you through a task.
1st Person
1st person (“I,” “Me,” “My,” “Mine”) is not commonly used, but can be if the pronoun is necessary.
“We” is more often used in marketing collateral (“We are here to help!”), but can be useful in error states or tooltips to offer the user support to convey a more human tone i.e. “We could not find what you are looking for” or “We have automatically pulled in data for your reference.”
3rd Person
3rd person can be used if it is important to inform someone that a specific user has done an action, i.e. “Casey Coachman has closed the report.”
Formatting
Follow these tips to help your users effectively scan and understand content.
Dos
- Use subheadings, whitespace, and bold main-points
- Group related content together into smaller sections
- Use parallel sentence construction in lists (repetition of a chosen grammatical form)
Parallel: “Francis has experience teaching classes and tutoring students”
Not Parallel: ”Francis has experience teaching classes and has tutored students”
- Use consistent styling
Avoid
- Avoid walls of text with no formatting
- Avoid centered paragraphs of text since this format is hard to read and scan
- Avoid redundant words as users will usually skip redundancies
Formatting Rules
Periods
Use periods in help and description text. Only use one space after a period. Avoid periods in headers, titles, tooltips, field descriptions, and menu names. Don’t use them in a list unless that list item is a full sentence.
Hyphens
Use a hyphen without spaces on either side to link words into single phrases (i.e. first-time user). Use a hyphen with a space on either side for ranges other than times and dates (10 - 20).
Numbers
Spell out whole numbers from zero through nine and use numerals for 10 or greater. Spell out a number if it begins a sentence. Consider rearranging the sentence if the numeral form makes more sense to use.
Dates
When using numerals, the date format is MM/DD/YYYY. For date ranges, use numerals and a dash as the separator with no space “08/31/2019-05/31/2020.” For localization purposes (adapting to the needs of different countries or regions), we should spell out Month, Day and Year “March 3, 2021.” That way, MM/DD/YYYY won’t be confused with DD/MM/YYYY. Use whichever format makes sense for the content.
Time
Use numerals with AM or PM. Always use minutes, even for on-the-hour time “12:00 PM.” When time zones are needed, use a space between the time and the zone “12:00 PM EST.”
Tooltips
It’s recommended that tooltip character count be kept to 150 or under.
Paragraphs
It is a general rule to keep paragraph widths no longer than 588px or about 90 characters for easier scannability. This rule can be broken up to 800px if the text needs to be longer to match the context.
Commas
Use Oxford commas (a comma immediately after the second to last term in a series of three or more terms) when listing items in a sentence, i.e. “Access an organization's outcomes, key metrics, curriculum, and store its important documents.” These commas provide clarity around the separation of items in the list.
Use of plural
Do not use optional plural, i.e. "(s)." Use the plural form except in cases where it is very likely to be singular.
Capitalization Rules
Watermark uses sentence case, title case and uppercase. Terms/features/components/roles like “action type, leads, institutions, and students” are not capitalized in body content. Do capitalize proper nouns.
Title case
- Content headers (page or card headers)
- Sidebar menu (navigation component)
- Dropdown menu options
- Text links
Sentence case
- Body content
- Empty states
- Tooltips
- Snackbars
- Dialog and modal headers
- Radio and check box options
- Tags (tag input component)
Upper case
- Buttons (primary, secondary, disabled)
- Eyebrow titles
- Tabs
- Column Headers (table)
- Tags (status tags)
Small Content Guidelines
Tips for writing labels for commands and actions.
Do
- Reflect the state that the system will move into, i.e. “Expand” or “Open”
- Lead with verbs for immediate action, i.e. “Submit Documents”
- Use hint text or toggletips if more information is needed
Avoid
- Avoid Generic Language, i.e. “Get Started” or “Learn More.” This is not good for screen readers and doesn’t set expectations for what comes next.
Instead, try to describe what the action will lead the user to, i.e. “View Documentation” or “Sign Up.”
Tips for writing short text fragments or phrases, i.e. headlines, links, email subjects.
Do
- Set expectations specifically and concisely with user terms
- Front load (place in the beginning) with key terms
- Micro copy should be understood on it’s own
Good UI copy empowers users to complete key tasks with speed and ease, reduces errors, improves accessibility, and sets expectations.
Structure Techniques
Follow these techniques for easier comprehension of large sets of content.
Provide Information in Layers
To avoid overloading information all at once, you can provide key information up front with links to dig into more details on additional pages or views.
Do
Avoid
Inverted Pyramid
This format organizes information in order of importance with a focus on the top of the page. This works with how users tend to read less and less as they scan down the page.
Rule of Twos
This is a technique you can keep in mind to include the most important information in the beginning by including key words or concepts within the 2 paragraphs, first 2 sentences, or first 2 words. This method works with how little users tend to read.
Examples
“Document achievements as you make your way through your academic journey.”
“Submit a work request to apply changes to your system.”