core guidelines

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.

You can also use the present-perfect tense with the past participle for actions that have occured in the past but continue into the present, i.e “The dog has caught the ball.”

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.

Be cautious using the passive voice where you include the actor receiving the action, i.e. “The ball is being chased by the dog,” or verbs leading with “to be” or ending with “ed” (past participle).

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.”

Back to Top