How to Use WordPress Contextual Help to Improve UX (5 Steps)

Chaosamran_Studio / stock.adobe.com

In its most basic state, the WordPress dashboard might not seem like it would be that intimidating of a space. Menus are relegated to the sides of the page. The workspace remains ever present in the center.

For many end users, however, that’s not the common perception. Even jargon as seemingly clear as “Posts” vs. “Pages” can trip up WordPress users if they’re new to the platform or coming to it without a shred of tech savviness. Never mind what happens when you add a premium theme or an array of plugins that increase the complexity of the platform and interface.

This is where WordPress contextual help can come in handy. The Codex explains:

“Ever since WordPress Version 3.0, every built-in Administration Panel has contained a contextual help section providing additional information to the user on how to navigate the various settings displayed in that admin panel. This helps WordPress keep the main part of the admin panel clear and concise by eliminating unnecessary text that regular users don’t need to see on a regular basis.”

But it’s not just about space-saving. It’s also about providing targeted help to users within the context of what they’re working on. This is vital to consider, alongside site speed and security, of course.

There are a number of ways in which you can provide extra support to your WordPress end users, whether you be a web developer, maintenance professional, or theme or plugin developer. WordPress contextual help is the one we’re going to explore today.

What Is WordPress Contextual Help?

Contextual help for WordPress, utilizes an ever-present Help tab tucked into the top of the admin screen.

It provides users with quick notes on the current admin screen they’re working on. Let me show you how this works.

This is the default WordPress contextual help screen:

As can be expected, it provides a brief overview of what users are seeing in the admin screen and how to utilize it.

Now, look at the Users contextual help screen:

All of the information inside the WordPress help tab now corresponds directly to the Users menu and functionality.

Do We Even Need to Worry About Contextual Help? 🤔

There are a number of ways to provide help to WordPress users.

For WordPress plugin and theme developers, you can provide:

A screenshot tour of the tool as iThemes has done or a full demo like the ones you find in the Envato marketplace:

A list of FAQs that anticipate users’ questions or formal documentation:

Real-time webinars and pre-recorded tutorials:

Ticketed support on WordPress.org or live support [link to live chat post] through your website as a provider like Pressable does:

For WordPress developers, maintenance teams, and other direct providers, you can provide:

Assistance through a support portal or dedicated email channels like Story Agency has done:

White-labeled WordPress dashboards with supporting materials. Unlike many of the other types of help we can provide, this one lives inside of WordPress. Tools like Video User Manuals and the WP 101 Plugin enable you to embed video tutorials and other guides right into the WordPress dashboard.

But that level of support assumes your end users will be willing to commit time to teaching themselves how to maintain and manage the content on their website.

[bctt tweet=”🖐️ #WordPress contextual help provides a more succinct and yet, still as helpful, means of introducing users to the CMS and its capabilities. ” username=”thewpbuffs “]

WordPress contextual help provides another way to introduce the CMS and its capabilities to people. This gives you the chance to fill in the gaps where plugins, themes, and custom post types leave it open to interpretation.

Why WordPress Contextual Help?

Nielsen Norman Group says that contextual help systems all share the same characteristics and, consequently, benefits to the end user:

1. They allow for constant support without interfering on the experience since the user has to engage with it first.
2. They’re written succinctly so as not to overwhelm with too much information.
3. They’re written descriptively and in plain language to ensure overly technical jargon doesn’t stand in the way of comprehension.
4. They comprise minimal space, which makes them less of a distraction.
5. Since they pertain directly to the tasks on the admin screen before them, it’s easy to keep users’ focus trained on what they’re doing.

Still unsure of why contextual help for WordPress is a smart choice?

Manualise has a good description of why WordPress plugin and theme developers need it:

“Almost every application has settings or functions that require reading a user manual to understand the purpose and all side-effects. At the same time, users don’t like switching to online documentation in the middle of some multi-step process. Context-sensitive help, or just ‘context help’, is a type of user documentation, which is smart enough to deliver the right content at the right moment.”

And Torque makes the argument for WordPress developers and maintenance pros:

“This is especially useful when you use it to leave behind instructions for the client (in addition to the help section that comes with WordPress out of the box).”

If you’d like to start providing the right kind of contextual help to your WordPress users, let’s look at how exactly you can go about doing it.

How to Add Contextual Help Screens to WordPress

This type of in-context help will be available for default WordPress menus. This means two things as far as you’re concerned:

1. WordPress has already laid the groundwork for you. Contextual help screens are simple and to the point and cover the basic essentials. That’s one less thing you have to worry about.

2. If you’re a plugin or theme developer, your tools won’t come with a Help screen out of the box. If you believe it would be beneficial to explain to users what to do within each admin screen, it’s up to you to create contextual help.

If you’re responsible for installing and maintaining plugins and themes on a client’s website, you might find a lack of help provided by the plugin or theme developer to be unsatisfactory.

For instance, here is the Yoast plugin menu screen:

As you can see, Yoast has not added a contextual help screen here. However, it has added help screens in other parts of WordPress to elaborate on SEO features it’s included for users:

This particular example exists on the Stripe Products screen. It’s an entirely different product and, yet, the help screen makes sense in this context.

But, what if you feel that your users need further elaboration when using this plugin right from the start? You actually don’t need to rely on the developer to create the contextual help text. You can do this yourself so long as you have access to the functions.php.

Here is what you need to do:

Step 1: Set a Goal 🥅

Decide what you need a contextual help menu for.

• Do you need to introduce users to the features of a plugin?
• Do you need to explain your theme’s unique settings and features for users that want to customize it?
• Do you need to elaborate on what a newly added custom post type is and how your clients should be using it?
• Do you want to provide links to additional reference material or tutorials that elaborate on advanced features or functionality in WordPress?

Figure out why you need to use contextual help screens so you know exactly where it needs to go in WordPress.

Step 2: Create a Wireframe 🖼️

Write out what you want to include in the contextual help screens and put it in a wireframe. This will help you code the necessary information when it comes time.

Make sure to include an Overview tab when you need to introduce users to a brand new functionality or features in WordPress. Then, break up the other important bits into logically organized tabs.

Don’t be afraid to format the text either. Just because you’re including brief notes and reminders to users doesn’t mean those short snippets couldn’t use a readability refresher. For example, use paragraph breaks and bolding as WordPress has done under the Comments contextual help screen:

If you find you have any more to say than what appears in this particular example, direct your users to additional resources with a sidebar. You can see that WordPress does this with the “For more information” section. This keeps the necessary notes within the context of the WordPress task and the more robust explanations in a space and website that’s set up to house them.

This next step will explain how to implement each of these elements.

Step 3: Open the Editor ✍️

Assuming the plugin, theme, or related menu already has its own admin screen, all you need to do now is add a few snippets of code to get your Help tab up and running.

Essentially, what we’re going to do here is use the get_current_screen() function to directly hook into the menu for the plugin or theme. The add_help_tab function will then allow us to inject our custom messaging wherever we want it to go.

To add contextual help to a plugin, go to the Plugins > Editor screen.

Then, select the plugin you want to edit from the dropdown list. Click Select.

Make sure you’ve clicked on the main plugin PHP file. This is the one we’ll be editing.

To add contextual help to a theme, go to the Appearance > Editor screen.

If you have more than one theme installed, make sure to select the right one from the dropdown and click Select. Then, click on the functions.php file.

This is the file we’ll be editing.

Step 4: Add the Help Tab to the Admin Screen 📑

Now, let’s add some code to the bottom of the selected file.

This first snippet is where we’ll tell WordPress to add a Help tab to the “current screen”. The current screen pertains to the particular plugin or theme we’ve selected. With the message we populate into the following fields, a simple new Help tab will be ready to go.

function add_context_menu_help(){
//get the current screen object
$current_screen = get_current_screen();
//content for help tab
$content = '<p>We need to talk about what is going on here. I don’t want to bore you with details, but this is some serious stuff.</p>';
$filler = '<p><b>Pay Close Attention!</b></p><p>Updates to the following settings could hurt the performance of your website. Before making any changes, please consult with your developer. Jason at 555-555-4321.</p>';
//register primary help tab
$current_screen->add_help_tab( array(
'id' => 'sp_basic_help_tab',
'title' => __('Help Me Help Me'),
'content' => $content
)
);
//register secondary help tab
$current_screen->add_help_tab( array(
'id' => 'sp_advanced_help_tab',
'title' => __('Further Info'),
'content' => $filler
)
);
}
add_action('admin_head', 'add_context_menu_help');


In the above snippet, you need to edit the:

• ‘id’ string
• ‘title’ label
• ‘content’ function
• $content message

You’ll also want to add or remove add_help_tab sections based on how many you want to include on this particular help screen.

Speaking of which, I should mention that the way the code is written above, this Help message will now display across all menu pages of your plugin or theme. So, for instance, I added this code to the Yoast SEO plugin PHP file. Here is what the main page now looks like:

My new tabs have even been added to screens where Yoast already had a Help screen present:

If you’d rather create individual Help screens for specific pages of the plugin or theme, make the following change:

function add_help_screen_to_yourpagename(){
//get the current screen object
$current_screen = get_current_screen();
//show only on social page
if($current_screen->post_type == social && $current_screen->base == 'edit'){
$content = '';
$content = '<p>We need to talk about what is going on here. I don’t want to bore you with details, but this is some serious stuff.</p>';
$filler = '<p><b>Pay Close Attention!</b></p><p>Updates to the following settings could hurt the performance of your website. Before making any changes, please consult with your developer. Jason at 555-555-4321.</p>';
//register primary help tab
$current_screen->add_help_tab( array(
'id' => 'sp_basic_help_tab',
'title' => __('Help Me Help Me'),
'content' => $content
)
);
//register secondary help tab
$current_screen->add_help_tab( array(
'id' => 'sp_advanced_help_tab',
'title' => __('Further Info'),
'content' => $filler
)
);
}
}
add_action('admin_head', 'add_help_screen_to_yourpagename');


Note the spots where we’re directing WordPress to only add a help screen to one specific page.

Step 5: Add a Sidebar to the Help Screen 📊

This last step is optional. However, if you have additional documentation, video tutorials, or a support portal you want to link out to, a sidebar in the contextual menu is a good idea.

To add this to the menu, here is the code you need to insert into the same PHP file:

//add a sidebar to the help menu
function add_help_sidebar(){
//get the current screen object
$current_screen = get_current_screen();
//add the sidebar
$current_screen->set_help_sidebar(
'<p><b><a href="https://yourdomainname.com" target="_blank">Gold Plan 24/7 Support</a></b></p><p>Have more questions? Need urgent assistance? Get in touch now.</p>
);
}
add_action('admin_head', 'add_help_sidebar');

To show you how this works, I added it to my Yoast Help screen:

I now have a direct link to my support portal in case Gold members run into urgent trouble and need assistance.

Wrapping Up

It might seem like such a simple thing, but being in the right place and at the right time for your plugin or theme users, can make a world of difference in terms of their experience. The same goes for those of you white-labeling WordPress for your web development or maintenance clients. We here are WP Buffs help our clients with setting up contextual help as well, in case you’re in need of more hands-on assistance.

With something like WordPress contextual help, you can provide gentle guidance along the way, ensuring they know what to do even without your direct assistance. And, if they run into problems, this gives you a chance to again be their trusted WordPress provider who helps them out of any jam.

Want to give your feedback or join the conversation? Add your comments 🐦 on Twitter.