Principles
This a living document, meaning that is always growing and changing, just like ZUI, just like language itself. Writing in Zywave products should be:
- Clear and Concise
- Easily understandable
- Useful/helpful
- Actionable, whenever possible
- Motivating or persuasive, when necessary
Voice & Tone
Tone is simply voice applied to a specific context. That context includes both the
circumstances of the communication, as well as the audience. The core personality of your
voice should still shine through in any communication, but it should do so in a way that
makes sense given the exact situation. Voice is the persona who's "speaking" when you
write. You can think of the Zywave product voice as the core personality of the speaker
who is talking to the user. Zywave's voice can be described as:
- Approachable
- Genuine
- Empathetic
- Clear
- Conversational
- Knowledgeable
Audience
It is important to note we have a different audience than the marketing or content teams
because this is a style guide specific to writing in our products
- Our audience is product users
- Our audience will vary from product to product, and potentially will vary
inside products depending on who is using it (HRc potentially has 3-4
different audiences using it: broker, broker admins, clients, etc.) - Our audience could be viewed as a combination of both marketing and
content's audiences, but a little more relaxed
Grammar and Mechanics
This is the meat and potatoes of the style guide. It covers the usual topics and how they
impact both copy and microcopy/web elements. If you're unsure about any on-screen-text,
especially if it isn't address in this style guide, ask a UX Writer. We're nice and don't mind
answering questions.
Capitalization
- Use sentence case for everything. Sentence case is capitalizing the first letter of the first word and none of the others.
- Always capitalize the following words: Partners, Zywave positions such as Partner Support (Zywave Consultant, Project Manager, etc), Help (when referring to the Help section), and the first word after a colon
Punctuation
- Periods: Skip periods and unnecessary punctuation on single sentences. This help readers scan text at a glance. Avoid using periods in single sentences in these: Labels, Hover text, Bulleted lists, dialog body text. Periods should be used on: Multiple sentences, any sentence before a link
- Oxford/serial comma: Use to the comma to avoid potential confusion
- Exclamation points: Use them sparingly, don't use more than 1, even if you're really, really excited about something
- Ampersands: Only use ampersands when conserving space is important, ideally only on buttons, or if it is part of a company or brand name
- Semicolons: They usually support long, complicated sentences that could be simplified, shortened, or split in to 2 sentences
- Quesion marks: Don't use punctuation in a page title/heading unless the title/heading is a question
Lists
- Use lists to clearly and simply present steps, groups, or sets of information
- When writing a list, use the serial/Oxford comma
- Use numbers when the order of the list is important, otherwise avoid them
- Only use punctuation if there are multiple sentences in a list item
Numbers
- Spell out a number when it begins a sentence, otherwise, use the numeral.
This includes ordinals (-st, -nd, etc), too. Using the numeral saves a bit of
space, which is usually important. If it feels weird to use '1' instead of 'one,'
just go with your gut.
Bolding and Italicizing
- Using bolding to emphasize an action, link, or button you are referencing
- Avoid italicizing. Italic fonts don't appear as clearly as bold fonts. The
exception being normally italicized things, like titles of books or movies.
Active/passive voice
- Use active voice
- Avoid passive voice
- Write positively whenever possible, avoid 'not' when possible
Contractions
- Use them, especially to save space in web elements, like buttons. However, sometimes "do not" can give more emphasis than "don't" when needed.
New vs. Old
Always try to use what is defined in this style guide. If what is in the style guide obviously does not
match what is live in product, consider the following:
- How noticeable is the difference? Use what is laid out in the style guide,
unless it will be distracting or obviously different from what is in product. - Can the text in product be updated or changed to match the style guide? If
it cannot be changed at the same time as the text you are adding or
updating, when can it be updated or changed? - How often will the product be updated? Will it be a long time before the text
in that product is updated again? You may want to use this opportunity to
get the text up to speed, even if it doesn't perfectly match the rest of the
product. - Is there a middle ground between what is in the style guide and what is in
the product that makes sense to use?