Intro

This section provides WalkMe content guidelines. Most of these guidelines align with SAP Fiori UI text design patterns and most User Assistance (UA) Style Guides. However, a few rules differ to better align with the tone and learning experience we want to provide within WalkMe experience.

Tone and Language

The tone and language we use should always be friendly and make the user feel confident.

• Use American English. Use Standard American English spellings, capitalization, and punctuation in all content.
• Word economy and clarity. Make your content conversational, clear, and concise. After you write something, read it aloud. This is a great way to validate that what you wrote makes sense, is well written, and is appropriate to your audience.

For example, you wouldn't tell your child, “Hey Charlie, would you please enable the kitchen light.” Instead, you'd say, “Turn on the kitchen light.”

Word economy and word choice is important. It might take a little longer to write, but it makes content much easier to scan and understand. Don't make users wade through dense prose.

• Avoid jargon. Don't use jargon unless it’s necessary, in which case it should be defined. Avoiding jargon and colloquialism also makes localization (translation) easier.
• Use present tense. Use present tense in most circumstances unless you have a definite time or date you need to refer to.

Correct (present tense): After submitting the request, your new account balance appears.

Correct (future tense): We'll update your account balances every night at 11:00 pm (Pacific time).

Incorrect (future tense): After submitting the request, your account balance will appear.

• Use active voice unless it sounds extremely awkward. With active voice, the subject performs the action the verb describes; with passive voice, the subject receives the action of the verb.

Passive voice example: Several improvements have been made to the product.

Active voice example: We’ve made several improvements to the product.

• Use of second or third person.
  Second person refers to the writer/speaker addressing the person reading the content—that is, “you” is the subject of the sentence. For example, “You can email the data to yourself.” Use the second person when writing steps. Much of the time, the “you” is implied and left out of the sentence. For example, when you say, “Click Add,” the “you” is implied at the beginning of the sentence but is not explicitly stated.
  
  Third person refers to addressing someone who is not the speaker/writer nor directly the reader themselves. For example, “Only Admins can enable this feature.” (The reader might be an admin, but it is not saying, “You can enable this feature.”) This might be necessary when the intended audience of an article is different from the subject the speaker is talking about.
• Don't anthropomorphize the product. Follow this general rule from the Microsoft Manual of Style: “Avoid giving hardware or software human characteristics or emotions. [...] Avoid words that convey emotions (refuses, wants), behavior (forces, tries), and intellect (know, realizes).”

Titles

Keep your titles descriptive but concise. Titles should be both browse- and search-friendly. Think about what terms customers would use when trying to find help.

Use sentence case. It reads easier and avoids confusing common words with proper nouns.

Use present tense verbs for titles of task-oriented flows and onboarding tours.

Excitable Punctuation

Avoid exclamation points and other over-the-top celebratory language and punctuation.

Numbers

Use Arabic numerals (1, 5, 10, 100) instead of text (one, five, ten, one hundred) in your content. Use a thousand separator comma for large numbers (1,000).

For instances where you want to tell the reader to select an option, say “select an option,” not “select 1 of these options.” Similarly, when introducing a list of options/choices/things, use “provides these options,” not “provides 3 options.” This approach future-proofs the content if we add/remove options from the list.

Punctuation

Oxford (Serial) Comma

Use the Oxford (serial) comma for lists of three or more items.

The Oxford comma also reduces confusion:

• “Transactions, inventory maintenance entries, purchasing and receiving activities” indicates that there are 3 distinct activities.
• “Transactions, inventory maintenance entries, purchasing, and receiving activities” indicates that there are 4 distinct activities.

Periods

• Do not use periods in titles or clickable WalkMe buttons.
• Use periods at the end of complete sentences, regardless of sentence length.
• Do not use periods at the end of standalone hyperlinks, unless it’s a longer, complete sentence where the lack of a period would look weird.
  Good rule of thumb; use a period if the sentence is 5 words or more.
  
  Examples:
• For more info
• Read more
• Find out more about reversing journal entries.

Quotation Marks

In American English, commas and periods go inside closing quotation marks. Question marks and exclamation points go inside closing quotation marks only if they’re part of the phrase being quoted; otherwise, they’re placed outside the quotation marks.

Instructional Text Conventions

Indirect vs Direct References

Modern applications tend to be multi-device. They are often designed to run on desktops, mobile phones, tablets, etc. This implies that the screen layout and user interface elements (including their labels and any text associated with them) may look different. Keep this in mind when referring to the user interface and its elements. Don't get too specific.

Examples

Familiarize yourself with the pros and cons. The approaches don't necessarily exclude each other. In the same text, there may be mainly indirect formulations, and you only resort to click level for tricky aspects. When using click-level formulations, try to be device-neutral.

Check out the Fiori Guidelines.

Image Icons

When referring to “action” image icons in instructional steps, refer to the action, not the UI element.

Examples

In general, avoid telling users to do actions that are UI functions, like “Select Search”. Instead, focus on what the user wants/needs to do.

Examples

• Add a new lead
• Edit the order details
• Search for a company
• Refresh the page

When you absolutely must refer to the action of selecting a UI component, don’t use the icon name or image in your instructions; focus on the action.

UI Action Verbs

As said before, we strive to not make specific click-actions in the UI. However, it is not always possible to avoid this. These are the action verbs for instructing the user to do something in the product UI.

• For tabs, links, or buttons, use select, if you cannot write around the action in another way.
• For checkboxes, use select.
• For dropdown lists or places where the user is choosing from a list of options, use choose.

Formatting Text for UI Text Click Actions

When telling the user to do something in the UI, use bold text for the UI string.

Bolding Rules

In general, use bold text in guided walkthroughs to instruct the user to click, select, or choose something in the UI, as described in the previous section.

That said, you should also bold text when calling attention to a specific UI term for text clarity.

Examples

Focus Instructional Text on Action and Purpose, not UI Mechanics

When telling the user to enter (type) a value in an open text field, use the verb “Enter”.

Examples

Dates

Generally, unless you’re reflecting exactly what’s in a screenshot of the UI, use the “Month Number, Year” format; for example: January 1, 2024. To avoid regional confusion, do not use the DD/MM/YYYY or MM/DD/YYYY formats.

Predictive Links

Links should prompt the user to click on them. The user should know what to expect when clicking the link. Never use “click here” and “this article.” Instead, use something like, “Refer to the SAP help” or “Learn more about event types” and embed the link in that text.

Avoid UI-specific Directional Instructions

In general, avoid directional instructions (click here, there, and everywhere). Screen locations can change. Future-proof your content by focusing on the user action or the effect of the action.

Keyboard Keys

Keyboard keys should be capitalized and bolded. Use "press" as the instructional verb.

For example:

• Press Enter.
• Press Shift+Control.
• Press the Spacebar.
• Press Tab to move between columns.

Checkboxes

Turn on

• Select Include both open and closed accounts.

Turn off

• Clear Include both open and closed accounts.
• Clear the Include both open and closed accounts option.

Validate checkbox state

• Ensure that include both open and closed accounts is selected (or not selected).

You vs. You’ve in Success Messages

When confirming completion of a task in a guided tour, use “you” not “you’ve”

Fill In, Fill Out, and Complete (Fields and Forms)

Sometimes, you need to tell the user to enter information for multiple fields on a page. As a general rule, we won’t use WalkMe to go step-by-step through each field. Instead, we will instruct the user to complete the required fields or fill out the form. For example:

• Complete the required fields
• Fill in the required fields
• Fill out the form

Your vs. A/The

In instructional text, use “your” as the descriptor only for things that are specific to the user. Otherwise, use “a” or “the”.

Your examples

• Add items to your cart.
• Place your order.
• Change your profile settings.

A/the examples

• Create a job posting.
• Find a supplier.
• Go to the My Items page.
• The Compensation Information page...