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.