Considering a different approach to onboarding new plugin users – feedback requested

General Discussion
1

How many times have you installed a plugin and thought, “Now what?”

A lot of plugins add a Settings link to their row in the plugin page and that’s often a good way to find the plugin’s settings and admin pages. Great. But, what do you do when you get there? Do you just know what to do next? Or, how to get started? Perhaps not.

If the plugin has pretty much just added a custom post type or two, you’ll automatically know what to do when you see the page – it looks just like any other posts admin page that you’ve interacted with before. But, what about other plugins… plugins with completely new interfaces or processes? You’ll probably be looking for a quick start guide or something.

Bearing in mind that I’ve developed a fair number of plugins already – with more on the way – it became apparent that some sort of onboarding process was needed. So, I wrote the code and called it a day. That was a few months back.

A few days ago, though, I had a thought. ~ Code Potent

Since ClassicPress already has a built-in “help” mechanism, why not leverage that for onboarding instead? This would mean less code to maintain and, well, it’s virtually sitting there waiting to be used for something useful. To make sure we’re on the same page, I’m referring to those little Help tabs that appear on most admin pages up near your username.

Now, you’re probably thinking… yeah, but who ever clicked on that tiny little Help tab way over off to the side? Who ever even sees it? How is that going to do any good? And I can’t disagree. So, I’ve built a small plugin as a proof of concept and would like to get your feedback on what I’m thinking.

image
image1455×417 26 KB

After activating the plugin, nothing out of the ordinary happens. The user is not hijacked redirected to the settings page – I hate it when plugins do this. The way I’m thinking it will work is that (only) the very first time you visit the plugin’s own admin page, the help screen is already popped out, as depicted in the screenshot. Then, on subsequent visits, it would be hidden as usual and users would have to pop it out themselves if they needed it. Moreover, the user would know it’s there…and where to find help, info, and resources…without my having to jam it into places it doesn’t belong. I think it’s a very unobtrusive way to achieve the goal of making sure users get off to a good start with a given plugin.

As I’m considering implementing this across my (larger) plugins, I’d like to know what you think about this approach to onboarding new users.

Thoughts?

9 Likes
2

I think it’s great, I really like the approach since it doesn’t hijack the experience but does give the user a guiding hand the first time they visit the plugins admin page hopefully driving longer adoption.

I also think this part is especially great, knowing where to go for help provides a great user experience that doesn’t lead straight to uninstalling because you don’t understand or posting a support issue that is already addressed somewhere but hidden under an obscure menu.

Now I just need my hands on a plugin that implements this so I can test it in the “real world” :wink:

1 Like
3

That’s a very neat approach and I may well adopt it!

2 Likes
4

I did that with my Testimonial Basics Plugin…been a long time since I looked at the code. The nice thing about it is that it’s there when you are working with the plugin options. However if the settings API is what you are using there is usually adequate space in the options panel to provide additional docs.

2 Likes
5

It’s great to see positive feedback rolling in! Awesome!

For anyone who’d like a leg up on such an implementation, here’s a working proof of concept, stripped of everything but the necessities.

I figured someone, somewhere must have at least tried it! I agree that using the settings API does allow for some inline documentation, just, no real onboarding… it’s more of a dump-you-off-and-let-you-figure-it-out kind of thing … no docs, no forum link, no contact email… the things that only matter when they matter, I suppose. Here, I’m using the contextual help API for the implementation.

Sidenote: the plugin linked above is only a PoC… I didn’t add any translation functions as it wasn’t necessarily intended for wide public consumption. Don’t spank me on it!

2 Likes
6

I know you said an article about this would be awesome…I just didn’t have time to do it. Instead, I spent a bit of time today and spun up the PoC linked in my previous post. Thanks for the inspiration to get it out there somehow. :+1:

1 Like
7

Gotta say thanks for the effort you put in around here Code Potent !

2 Likes
8

It’s really a lot of people’s efforts around here…I just crow about it most. :rooster:

1 Like
9

I like it.

1 Like
10

Very nice. I like it too. Might be something to think about adding to Classic Commerce.

I totally agree. And now that I have done the CC docs it would be good to make it really clear to people how they can easily find them.

3 Likes
11

I think this would be a great addition to CC – in my mind, that’s exactly the kind of “beefy” plugin that would benefit from such a thing. It’s one of those that can feel a bit overwhelming for the uninitiated. And yes, it would be a shame if people missed all those docs that you have worked so hard to get ready!

2 Likes
12

I’m not sure I even knew that the Help tab was there.

1 Like
13

For 3rd party plugins like ours, we have to add the code to register the help tab (and content) in the system. A lot of plugins don’t include the tab. Since it’s not too hard, I guess they just don’t realize it’s there either.

For the core screens, though, you’ll find this help tab on virtually every screen…each with its own contextual help.

1 Like
14

When I start working through my dev list, I’ll take a detailed look at this and see how I can use it.

Thanks for posting.

2 Likes
15

Funnily enough, I was disappointed when Gutenberg chose to make their own help screen. They don’t show the built-in help at all.
I have put plugin help in the help screen for plugins I write.
Too many plugins try to put something in the admin bar, and it gets cluttered. One plugin I was using for analytics moved their menu link from the side menu to the admin bar and I couldn’t find it (since I never look at the admin bar).

2 Likes
16

I like this approach too, it’s a nice intermediate step in between just showing the settings with some inline help and taking over the whole screen with a wizard (I find that latter behavior annoying, especially if it happens immediately upon plugin activation and hides the admin menus).

Expanding the help on the first run through the plugin is a nice touch. I wonder if it might be better to leave the help expanded by default not just on the first run through, but until the user clicks the “Hide” button specifically? Not sure how difficult that would be to do under the current structure of that code.

Another idea that I’ve had, but haven’t seen any plugins implement, is for more complex plugins that really benefit from a wizard setup: display the wizard steps only inside the plugin’s settings screen (i.e. don’t obscure the rest of the admin menus), and then show all of the plugin’s settings once the initial setup is done.

3 Likes
17

Hey @james and @anon71687268 have a look at the new setup wizard Paul added to Shield Security. It opens in a new tab. It is by far the best setup wizard I have seen.

I LIKE the direction you are moving here.

2 Likes
18

@james, Yeah, I’m not a fan of wizards either (or anything, really) that hijack an expected outcome in the dashboard, and even moreso if it goes full chrome to do so.

Regarding the idea of keeping the help tab popped until the user closes it: I did consider this, but, wasn’t sure how it would be taken. I envisioned John Q User sitting there screaming at the screen about “Who the hell does this guy think he is…” …and worse. :slight_smile: But, that’s an interesting idea…and it wouldn’t take much to implement.

I like your idea of how a wizard might work. In fact, to me, this sort of falls under ClassicPress 101 – “Keep your screens to themselves.” This goes for notices, enqueues, alerts, etc. If a plugin is loading its assets and functionality willy-nilly, it gives me low confidence in the work.

@Web242, I’m already using Shield, so, I’m afraid (or is it pleased!?) that I won’t see a wizard. That said, Shield is one of those plugins that can actually benefit from a wizard and I hope the execution was top notch. If I’m completely honest, I don’t care for the implementation of the admin screens in the Shield plugin…although, with so many screens… I guess, what can you do?

3 Likes
19

I’ve done this myself (in a small way) in the odd plugin I’ve created. It almost certainly is an underused facility though I wonder if an overlay might be better than a push-down.

I’ve used a plugin in the past that had context-sensitive help in a slide-out overlay, appearing from the right side of the page. I actually thought it worked really well but I can’t for the life of me remember what plugin it was now. Not standard WP/CP practice perhaps but it worked well.

So I agree, this does have the potential for improving help content.

3 Likes
20

I’m very much of the school of thought that plugins (and themes for that matter) should not change the layout or presentation of core “things” (even when it’s on their own pages.) Due to this, I’d be unable to implement it as an overlay. Mostly, it’s a consistency thing… one plugin does this, another plugin does that…and next thing you know, the dashboard looks like this.

I’m really digging the idea of using the core contextual help functionality as a first course…mostly because the only work involved is registering the tabs and adding the content…and core maintains the entire framework for you. It’s likely that I’ll only have a short paragraph or two in there with links to whatever might be relevant (docs/issues/requests/support) to the given plugin, so, the idea of not having to reinvent a wheel is very appealing.

I also like side slideouts at times. I built one just yesterday to flyout code examples when needed. It works well. My only complaint (as a developer) is that I had to add more code to handle responsiveness and showing/hiding the content which means more code to maintain going forward. Not a big deal in this particular case as it wasn’t a lot of code…but it adds up project by project.

5 Likes