Writing documentation and other supporting content can be hard, especially for plugins. Why? There are many levels of user; developers, web ‘assemblers‘ and DIY-ers, all of whom will need to understand your content. You may think you’ve covered everything, but things that are obvious to you may be well beyond what some users can grasp.
Take one of my plugins as an example, a WP Job manager addon called WooCommerce Paid listings:
Add paid listing to WP Job Manager functionality powered by WooCommerce
To me it’s pretty obvious that this plugin integrates Job Manager with WooCommmerce, but to date I’ve had at least 10 users boggled by the fact you need to install WooCommerce first to use it. That’s insane given the name of the plugin, and the descriptions I provide.
The way I see it, there are the following problems:
- Some users see the name of the plugin, install, and just hope it works how they want
- Non-technical users just don’t understand some of the terminology we use
- If documentation links are not prominent, users won’t go looking for them without direction
- Even if users find your documentation, if they cannot find the answer quickly they give up
So with the growing popularity of WordPress, influx of do-it-yourself users, and these support issues growing, what can we do to improve matters?
Spell things out clearly
It may seem obvious to you as the developer but never underestimate those “special” users. Spell out features and requirements clearly, in simple terms, so that they won’t try to fill in the gaps (in their knowledge) with what they hope the plugin will do.
Add prominent documentation and support links to your plugin
When I add docs links to the readme file only, no one seems to read them. It’s infuriating. I often find myself manually linking users to the docs via email after they ask for assistance with something I know is covered.
Clik here to view.
Prominent docs links
Adding documentation links inside the plugin itself seems to help, for example dismissible admin notices aster install. Users will be much more likely to see them even if they jump in without reading anything first.
Admin pointers are also great, but can be harder to setup initially.
Help tab content can also be added within WordPress admin, but from my experience these are largely ignored and a waste of effort.
Make documentation simpler to understand
Once the user finds your documentation, ensure they can process it and get the answer they need without contacting you.
Separate developer docs from user docs
If you can, keep all developer documentation separate – if its there it will only frustrate end-users as the terminology you use will be unintelligible to them.
tl;dr
Avoid large blocks of text in your documentation and supporting content; eyes will glaze over. Use bullet points, actionable steps and short to the point passages. Step by step tutorials are also particularly popular with beginners.
Snippets are great but give context
I write lots of snippets and gists for achieving certain functionality, but you have to explain in context how to addd the snippet. When I forget to do this I’m always asked “Where do I put this code?” and 99% of the time its in the theme functions.php file.
Have canned responses ready
Clik here to view.
TextExpander saves loads of time
If all else fails, and you find yourself having to answer obvious questions often, do yourself a favour and get some canned responses ready to save yourself time. TextExpander is great for this purpose.
I personally find the most useful to be one giving links to all the resources, one explaining about customisations (go hire someone to do this), and one giving links for the bug tracker.
Anything else?
Have I missed anything? Let me know in the comments.