The importance of stating the obvious

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.

Prominent docs links
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.


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

TextExpander saves loads of time
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.





6 responses to “The importance of stating the obvious”

  1. Pippin Williamson avatar
    Pippin Williamson

    Spot on, Mike.

  2. PhilJohnston avatar

    Excellent article Mike. I would add that there may be a simple but important difference in terminology in how types of users will find content.

    Usually “developers” will look for documentation while “users” will look for support. If you list the different types of targeted information under those separate headings it may help to direct the right users to the right information.

    1. mikejolley avatar

      Good point – I think thats accurate.

  3. Maria Scarpello avatar
    Maria Scarpello

    Great post Mike! I would add that screenshots seem to be very helpful for users, but can be misleading if you do not keep them up to date with UI changes.

    I’m also a big fan of formatting steps consistent across all your documentation and using bold for important information such as: Go to: Settings > Reading > Front Page Displays.

  4. Chris Howard avatar

    So, so true.

    And no matter how much documentation you’ve got, it will never be enough.

    I also find, there’s a large number of users who only want video tutes. Which kinda doubles the documentation workload. :s

    Recently I learnt how to display messages on content list and content editor pages in admin, which has enabled me to put key info I kept getting asked bang in front of users (mainly what the screen is for and how to get more help!).


    Use one of these actions:

    Content list: ‘views_edit-{post type name}’

    Content editor: ‘edit_form_after_title’

    The latter passes $post to your function (i.e. use myfunction($post)) , so grab that and use $post->post_type to check you’re on the right page before showing your message.

    Thanks for another great article, Mike.

  5. David Decker avatar
    David Decker

    I experienced just the same with my (free) Genesis plugins: some users just cannot read. There is stated “Genesis” all over the place, and that it is premium and required for that add-on plugin. Still, I get bad ratings and complaints, to say the least. This really sucks!

    They even complain when they get my little admin message, that checks for Genesis first, and if not there, puts out a user notice. They said to me I would “cheat” users – this is really shocking. There are quite some users who only see always the “negative” things.

    This is sad, because my work for the free plugins happens in my spare time. A huge discouragement…

    Also, I noticed that quite a lot users never see my plugin pages at as they ONLY search & install via the Admin Dashboard Plugin install. It shows me, that the admin system of WordPress works perfect, but the process and the user info it puts out is way too minimal for many, many users. Most of them see the plugin page on, including FAQ and Installation tips, for the first time, when they get a support email from me with those links.

    To make it even more crazy, I get also complaints from users that my documentation were to long to read so they never tried it.

    No matter how you do it, how many time you invest, a certain amount of users will just NOT be happy with what you do and will make you a lot problems sometimes – just for nothing. They will not read, or cannot read, or are just out to “be in conflict with people” — at least it seems to me in this way, sometimes…

    These are some of the lessons I learned in the last 2 years, publishing little helper plugins for WordPress.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: