Practical WordPress Development

WordPress Documentation For Free and Premium Projects

If you spend time maintaining a WordPress project – be it a theme, plugin, or application, and regardless of if it’s free or premium – then you know the challenges that come with writing and maintaining documentation for your project.

Sure, I think many of us who build and maintain projects consider documentation a form of support, but when you ask a customer to define support, you’re more likely to hear about their ability to communicate with someone through a forum or a phone call (depending on your service).

I mean, case in point, when I think about support for my cellular service, I don’t think of documentation of Sprint’s network. I think of talking to a person.

Anyway, all that to say is that over the past few years of working with various types of projects – both on my own and with my team – the trend seems to be that documentation for free projects is expected, but ignored, whereas documentation for premium projects is not only expected, but also read.

But I write this to ask if this is something the rest of you guys have noticed, and, if so, if there isn’t something that can be done to improve this particular situation or it’s simply the nature of the economy.

The Two-Faces of WordPress Documentation

Two Faces of WordPress Documentation

I believe in Documentation.

Obviously, I can only speak in terms of my own experience so I hesitate to discuss for fear of making a hasty generalization, but I’ve spoken with enough developers elsewhere to know that I’m not the only one experiencing this issues.

In short, when it comes to maintaining a number of free WordPress projects, the degree to which users read provided documentation is at a minimum.

Free Plugins

WordPress Plugin Repository Homepage

WP Audio Player at the WordPress Plugin Repository

For example: Every single one of my plugins includes…

  • A WordPress plugin repository homepage that includes a forum (in which I engage)
  • A FAQ section that is populated when enough questions are, y’know, frequently asked
  • Descriptions and notes on the homepage of what the plugin supports
  • A page on this blog that documents the project as well as any significant updates
  • A link to the above homepage which also includes way to contact me
  • And excessive code comments (just in case developer’s want to add or understand what I’m doing).

Personally, I view all of the above as excessive as it creates somewhat of a dissonant experience. We’re giving users too many ways to find support so their just kind of grapple with whatever seems easiest and go from there.

I don’t fault users for this one bit.

But the thing is, many of the questions that I receive in comments and or emails are already answered in the forums, in previous blog comments, or on the plugin’s repository homepage.

Interesting, right?

What appears to be happening is that when user’s are looking for support for a given plugin – though I imagine themes are subject to this as well – they are more concerned with getting an answer than spending time prodding around the n-number of places we’ve given them to look.

I don’t think we can fault them for that, but that’s not to say that I don’t believe they have a responsibility to look first, ask second.

Again, I think having so many ways for them to look for support continues to fragment the experience and makes support difficult and frustrating, at times. This is why it’s important to have a better support system.

Premium Plugins

Standard Theme Documentation

Documentation For Standard Theme, a premium WordPress Theme

On the flip side, my experience with providing documentation for premium support was an exponentially better experience. In short, the two retired projects included the following:

  • A homepage outlining exactly what the plugin did, including screenshots
  • A support forum accessible to those who paid for access to it
  • An online manual complete with screen shots that walked users through setting it up to using it

Rarely did I ever receive a support email, and when I did, I was sure to fold that question into the documentation and into the FAQ on a forum. From that point on, I almost never received the same question twice.

It’s also awesome because it continues to improve the quality of the forums and of the documentation thus making the experience for future customers, that much better.

That said, I can’t help but wonder if the disparity that exists between the two experiences is one, or both, of the following:

  • Is it that the WordPress Plugin Repository provides too many outlets to support, and premium projects managed by single developers or small teams funnel users into a more easily manageable system?
  • Is there something that happens that when a user has made a financial transaction, they feel more engaged with the resources provided to them and turn to them as true resources rather than directly to developers?

I’m asking these questions honestly, but I simply don’t know and would love to learn from those who have gone before.

But There’s More

As far as documentation is concerned, I’ve more to say on the subject, specifically around the topics of how people learn – you know, the whole auditory versus visual thing – but that’s subject matter for another post later this week.

Until then, I’m genuinely interested in you guys thoughts in all of the above. As I continue to move forward in working on moving back to the premium plugin model and working to consider where and how to host the plugins, support the plugins, and document the plugins, I’m digging the conversations we’re have ’em.

So have at it.


  1. Doug Stewart

    Here’s my theory: end-users tend to view free as less valuable than paid. The only investment they’re making in your project is one of time. As such, they’re entirely comfortable in moving on to the next plugin/theme/etc., so they’d rather get in, decide if your offering is worth gettin to know, and getting out. If they have to go looking for support/answers, they’re likelier to simply drop it and move on to the next one. Inherently, they view their time as more valuable than that of the developers.

    On the paid side of the house, there’s a sense that “I paid for this, I’m not going to waste my money, so I’m going to MAKE this work, dang it.”

    • Tom McFarlin

      I think you’re right. And to add to your thoughts, I think that free plugins breed this mindset of having a right to certain things – such as a degree of support – that isn’t necessarily explicitly stated anywhere.

      It’s assumed.

      Don’t read me wrong: I do think that if you offer a free plugin, there’s a degree of support you’re obligated to provide, but it’s minimal.

      On the other hand, with premium products, I think you make sure people get their money’s worth and then some. It’s the whole over-deliver thing :).

  2. Erik

    My experience is that the quality of documentation for a premium plugin is usually just a lot better than for free plugins, as properly documenting their plugin is taken seriously by the developer (as they should, you don’t sell a TV without a manual either). I’m not saying that developers of free plugins don’t, but in general the quality of documentation for free plugins is (understandably) not as good and usually an after thought. Hardly ever have I found the answer to my question via the WordPress Plugin Repository.
    Speaking for myself, actually asking a developer for help with a question is a last resort, I’d much rather find the answer on my own, this helps me learn and is much more rewarding, so proper documentation is essential. In the long run it would save the developer time as they probably would get less questions. For me I prefer paying for a well documented plugin, than getting a poorly documented plugin for free.

    • Tom McFarlin

      Hardly ever have I found the answer to my question via the WordPress Plugin Repository.

      Which is a real shame. In my mind, just because something is free doesn’t mean that we, as developers, shouldn’t be making it difficult for users to find what they are looking for on the plugin’s homepage.

      Above all other available resources, this is one place where answers should always be.

      For me I prefer paying for a well documented plugin, than getting a poorly documented plugin for free.

      And this seems to coincide with what Doug mentioned, and what my general opinion is.

      I’d still love to see the quality of documentation improve in the free repository, but that’s ultimately up to the developer of the plugin, but that’s an entirely different discussion for a number of different reasons :).

  3. grappler

    I think for plugins and theme especially on the repository there are two problem. First which you mentioned in the premium plugins

    This is not easily possible on the repository as you need to update the readme for the plugins and for the themes there is no such place.

    The second point is content management. There are only two pages available for a plugin: installation and FTQ. If we take your documentation as an example there a multiple pages.

    In general I think a clear search area is really important. That is also something that is lacking on

    On a personal note I have always like to search for my answers as I normally can find an answer quicker then it takes me to formulate my question and then wait about 24h to get a reply.

    • Tom McFarlin

      Search is key and it’s quickly becoming the UI of the Internet, IMHO.

      The second problem – as far as the free repository is concerned – is that we simply provide too many outlets to which the users can ask their questions.

      There needs to be a small number of ways that users can ask for help rather than a variety of ways.

  4. David

    Well, I read somewhere:
    Documentation is just like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing. :)

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑