Best Practices
  • 10 Minutes To Read
  • Print
  • Dark

Best Practices

  • Print
  • Dark

Common Best Practices

Always test content in your development environment

If you work in multiple environments, it’s a good practice to publish your content on your test environment before deploying it in production.


Organize content using Tags

Adding relevant Tags is a great way to keep your guides accessible and easy to find for your users.


Use contrasting colors for Whatfix widgets

Use contrasting colors for Whatfix widgets, to make them stand out/noticeable on the website. Make sure that your widgets are not lost on your interface.

Use the contrast checker available on this site to help you decide -


Be clear and concise

Use words and simple sentences. Keep the description in your tip simple and to the point.


Use Beacons to catch the attention of your users

Use Beacons to highlight new features and UI changes. Link Flows to beacons in case there is an associated procedure.


Don't exceed the maximum width in a tooltip or Pop-up

When inserting images in your content, ensure that they don't exceed the width of the tooltip or pop-up to avoid any distorted images.


Monitor the content performance using Whatfix Analytics

Remember to configure Whatfix Analytics to find out how your content is faring. Are your users completing tasks? Which step are they getting stuck at? What search terms do not give any results? You can track this data and use it to improve the performance of your content.


Use Control+Shift+V to copy and paste content while translating

When translating content in the UI, avoid copy-pasting content. The formatting of the content could get copied and may generate sync issues. If you have to copy and paste, use the CTRL+SHIFT+V (Windows) or  COMMAND+SHIFT+V (Mac) to paste content. These shortcuts copy only the value.



Use Flows for Product tours and Tutorials

Use Flows for sequential actions. For example: Product tour, Tutorials, and UI guidance.

Use simple descriptive names for Flows

Name every Flow clearly for easy retrieval during search. Use simple descriptive words that your audience is likely to use. Keep the title short. Use gerunds.


Do not use special characters while naming Flows

Do not use special characters when naming a Flow. Special characters may cause issues when trying to download the Flow as a video.

     :::(Info) (your title goes here)

If the Flow title includes spaces or any of these special characters (<,>,:,",/,|,,?,*,#,%,\s,\n,.), then they are replaced with an underscore (_) when the flow is downloaded as a PDF or a Video.


Use a brief description in tooltips

Use easy to understand words and simple sentences. Keep the description in your tip simple and to the point. 


Create Flows in a stable environment

Create Flow on production/live website which is stable and is not constantly being updated by code changes. If the underlying code of your application is being changed, it may break any Flows that you may have created.


Limit the number of steps to 15

Limit the number of steps in a Whatfix guide to not more than 15 steps. This helps your users understand the value proposition of your guides quickly and easily. 


Split long Flows into two parts

In case you can't keep the number of steps under 15, then consider splitting the guide into two and interlinking them. This keeps your guide crisp and simplifies user tasks.

When interlinking content, ensure that the button on the end message that links to the remaining procedure is titled appropriately. Use a short, action-oriented phrase.


Interlink Flow using a clear phrase

When interlinking content, ensure that the button on the end message that links to the remaining procedure is titled appropriately. Use a short, action-oriented phrase.


Make sure tooltips don't hide any UI elements on the page

Position the tooltips so that they don't hide any elements on your page. In certain cases, the tooltip could inadvertently hide certain important UI. 


Remove sensitive information using the Blackout feature

Remove personal/sensitive information using the Blackout feature. While creating a guide, use the Blackout feature to avoid capturing sensitive information like email, phone number, username, etc.


Use the Spotlight feature to prevent distractions for the user

Use the Spotlight feature to get the user’s complete focus on the element on which the tip is displayed. Users cannot interact with other elements when the Spotlight tip is active. 


Don't exceed maximum image width in a tooltip

When inserting images in your content, ensure that they don't exceed the width of the tooltip. Exceeding 270 pixels introduces a scroll bar.


Reduce the number of steps in a Flow using Smart Tips

Instead of creating individual steps for each field in a form, you can create Smart Tips that describes each field. This way all you need to create is a single step for the entire form asking the user to interact with the fields to find more information, thus reducing the total steps in the Flow. Also, the users can choose to see the tooltip help only for the fields they need information about, rather than seeing info for every field in the Flow steps.

Another benefit is that you can use the Smart Tips to validate user input ensuring the right information is entered. For more information, see Data Validation using Smart Tips


To create Flows, see Flows.


A Beacon must always be a part of a Beacon collection

A Beacon once created, must always be a part of a Beacon Collection for it to reflect on the page/application. A Beacon Collection is a group of Beacons belonging to the same page.

Create one Beacon collection per page

Always have ​one Beacon collection ​​per page​ in your application. Whatfix evaluates only one Beacon segment at any given time, so if two or more Beacon segments are active, only one of them would be evaluated. Criteria for evaluation depends upon the visibility settings or number of conditions (in case visibility settings are the same for two segments)

Provide URL paths for Beacon Segment across different Application environments

If you like to have the same Beacon segment work across application environments, it is better ​to provide URL paths instead of full URLs, else the Beacon segment in one environment may not work in another​.


Look for existing Beacon collection in a page

When editing or modifying a particular page to add new Beacons, please look for any existing Beacon collection for that page. Don't create a new Beacon segment/collection for a page if the collection already exists.

Configure when the Beacon should appear

  • Use the Visibility Rule settings to configure when a Beacon should appear. A Beacon disappears after it is shown to a user. You can control the frequency of a Beacon appearance as well from Visibility rules.

  • If you want to show a Beacon at a particular frequency like once daily, weekly every Monday, selected days of the week, etc. choose the Custom option with the date range defined under Visibility Rule settings.


See Scheduling a Beacon

Make Beacon reappear for all users

  • Once the Beacon show count is exhausted, it disappears on the application. In case, you want to show the Beacon for all the users again including those who would have interacted with it, use the Refresh Beacon setting.
  • Only an Account Manager can reactivate an existing Beacon.
    Also, be mindful of your date range settings when refreshing a Beacon. A past date in your visibility rules might not refresh the Beacon successfully.

See Refreshing a Beacon.

Self Help

Animate the Self Help tab to catch the user’s attention

Animating Self Help increases the chance to catch users' attention and help them find answers themselves.


Deliver specific contents to users using Tags

Segment guides using Tags so that users receive more relevant and focussed content.


Link your support articles

Add links to your support articles in the Flows steps to deliver more information. Use this wisely.

To configure Self Help, see Configuring Self Help.

Task Lists

Use task list for user training and onboarding

Use task lists for user training. Task lists can be used to ensure that your users can all perform certain basic tasks. For example, you can use a task list to design an onboarding list of tasks for someone who's new to your application.


Avoid listing more than 6 topics

Avoid listing more than 6 topics in the task list. Having a large number of tasks overwhelms users.


Enable sequential tasks so users cannot skip tasks

If the tasks have to be done sequentially, then enabling sequential tasks ensures that your users can complete each task only after the previous task is completed.


Deliver specific contents to users using Tags

Tags Segment guides using Tags so that specific content is delivered to specific users.

Introduce Self Help

The last task in the task list can also be used to introduce your users to self-help so that learning becomes continuous.

Track task list performance using analytics

Task list analytics includes completion rates at user and org level, user learning progress, individual task level data, how users are interacting with your content, etc. 


To configure Tasklist, see Configuring Tasklist.

Smart Tips

Make sure tooltips don't hide any UI elements on the page

Position the tooltips so they don't hide any elements on your page. In certain cases, the tooltip could inadvertently hide certain important UI.


Avoid unnecessary tooltips

Avoid adding tooltips for fields that are self-explanatory.


Add videos for better user engagement

Add videos within tooltips for better user engagement. Adding a video to your tooltip is a great way to engage your newly signed up users or to explain a lengthy process. Videos can also be included within the onboarding pop-up. Add videos using the Rich Text Editor.

To create Smart Tips, see Smart Tips.


Use Pop-ups to show important messages

Use Pop-ups to present important messages that your user segment must see.

Use Pop-ups for product/feature tour

Use Pop-ups to provide a guided product/feature tour to users.

Introduce Self Help and Task List

Use the last steps of your Pop-ups to introduce users to your other Whatfix widgets like Self help and Task list.


To create pop-ups, see Whatfix Pop-ups.

Video upload and embed

Configure video channel before publishing

Configure and authorize a video platform channel before publishing Flows. See, Uploading Whatfix videos to online video platform.


Use a brief description in tooltips

Ensure that the text in tooltips is clear and concise. Keep the description in your tip simple and to the point.


Review the tooltip position

Check the video once it is available to ensure that the tooltips are not cut-off in the Flow. If a tooltip gets cut-off, try repositioning the tooltip. Use the Preview Mode or See Live option to review the Flow every time you create or update it. See, Changing the tooltip position.


Add audio to your videos

Add audio to narrate text from your tooltip steps in Whatfix videos. See, Add audio to Whatfix videos.

Use the URL from the Flow embed menu to embed the video

When embedding your Whatfix Videos in Self Help, Task List and in other platforms, use the URL from the Flow embed menu. Never use the URL from your video channel.

The URL in the video channel changes each time an update is made. But the Flow embed URL does not change and renders the latest update as a video.

To get the embed URL,

1. Navigate to the Whatfix Dashboard.
2. Open the corresponding Flow from which the video was generated.
3. Click the Embed option.
4. Click Video from the dropdown.
5. Click the Copy iFrame button.
6. Paste the copied iFrame code in a text editor.
7. Delete everything except the video URL as shown below.
8. Add https: before the edited URL.
9. Use this final URL to embed videos.

Delete outdated videos in your video channel

A new video is created and uploaded every time a Flow is updated and published. Periodically check your video channel and delete the outdated videos.

Do not use special characters while naming Flows

Avoid using special characters (*, ?, /, \, etc.) when naming the Flows. They can cause issues when uploading videos.


To upload Whatfix videos to your video channel, see Uploading Whatfix videos to online video platform.

Was This Article Helpful?