Tips for Writing Effective In-App Guidance

For use cases, benefits, and caveats of each type of prompt and walkthrough, see Types of In-App Guidance. Also, check out the User Engagement module on Trailhead.

In-App Guidance Examples from AppExchange

For examples of different types of in-app guidance in Lightning Experience, you can install packages from AppExchange.

Voice and Tone

In general, use a conversational but concise tone when writing in-app guidance. For more voice and tone suggestions, check out these resources.

• Salesforce Voice and Tone Guidelines
• Trailhead: User Engagement
• Trailhead: Writing Style

Titles

Use keywords that emphasize the purpose and value of the feature or process to users. Avoid excessive exclamation marks.

For prompts, format your title with imperative phrases.

Example Prompt Title with Imperative	Example Prompt Title with Noun Phrases
Create shortcuts to favorite pages	Favorites are a way to create shortcuts
	New feature: Favorites

For walkthroughs, your title varies with each step.

• The first step of the walkthrough welcomes the user and summarizes the content of the walkthrough.
• The middle steps can be either instructional to describe how to complete an action or conceptual to provide information that helps users understand the use case, benefit, or purpose.
• The last step gives users encouragement for taking the walkthrough.

Headers (Docked Prompts)

The header follows the title, so use it to indicate to the user what type of information is in the prompt. For example, Important Changes, New Feature, or List View Tips.

Body Text

Elaborate on the title without restating it. Provide more information about the feature or process, mention the problem that the solution solves, or include common use cases.

Write in a minimal, straightforward style. Include content that’s directly relevant to the current task. Don’t include anything that users must refer to later. Focus on writing content that’s easy to understand and to execute.

Floating and targeted prompts support rich text formatting such as bold, italics, and underline. Docked prompts also support rich text but provide more options, including colors, links, and lists.

For walkthroughs, the body varies with each step.

• The first step of the walkthrough clearly states the goal and the benefits to the user before they start.
• The middle steps provide more details about the process or concept.
• The last step can include next steps or resources to keep the user engaged with the feature

Media

Keep users engaged, hold attention, or illustrate a complicated subject with optional images. In a docked prompt, optionally embed a video. For image and video requirements, check out Considerations for Creating In-App Guidance.

Buttons

Keep button names consistent. For the optional Action button, the label indicates where users are going before they click.

The Action button can also link to a helpful resource that’s accessible from their current environment. When choosing a resource to link to, think about content that helps users complete their current task or is part of the call to action. Avoid linking to resources that require more clicking outside, which can take users further from their current environment.