When I look at plugins to use on my website, for a client project, or for a review on EngageWP, one of the first things I look for is documentation. Whether the plugin is free or paid, documentation is, for me, as equally important as functionality and quality because it helps me to better understand what a plugin is about, how it’s used and what it can accomplish.

Documentation: Free vs. Paid

First, I don’t think the price level of a plugin (or theme) should determine whether documentation is available. Personally, if a plugin is free, I’m skeptical of using it without a decent amount of documentation (at least an explanation of how to use it). If you make a free plugin available on WordPress.org and you want people to use and like it, it should be documented. If a plugin is paid, I expect good documentation that can be read before purchasing or I won’t buy it.

Second, whether a plugin is free or paid, I believe that all documentation should be made available without purchase. I’ve seen free products with paid documentation and I’ve seen paid products with documentation hidden until after purchase. The reason I argue that documentation should always be free and accessible is because it’s a learning opportunity for anyone interested in using a product and, therefore, can be a deciding factor in whether someone ultimately chooses whether to use/purchase your product. If you offer a free product, upsell a more feature-rich version rather than documentation. If you sell a paid product, allow the documentation to serve as a way of answering many pre-sale questions. Product documentation should serve as a voucher for your product and a tool to boost usage and sales.

Document Basic Use

First and foremost, documenting the plugin’s basic use is essential, especially if the plugin does a lot. Often times, I’ve found great plugins on WordPress.org that have absolutely no documentation and it took quite a while before I figured out where things were and how to use the plugin. I think it’s no coincidence that these plugins usually have a higher number of support threads in the forums than well-documented plugins.

Document Developer Use

If your plugin or theme is intended or can be used for any type of advanced work, such as frameworks, the developer side of things should be documented as well. If you’ve developed an API for the plugin, show it off. While I won’t get on the subject of making products extensible as that’s a topic for another day, if developers are able to extend your product by way of an API or simple actions and filters, make that clear and easy to find rather than hiding it in the code.

Setting the Bar

I’ve used a lot of plugins in my time with WordPress, both free and paid. There are plugins I’ve been totally impressed with when it comes to documentation and there have been those I stopped using because of a lack of it. Here are a few plugins worth mentioning regarding documentation:

Advanced Custom Fields

ACF takes the cake on documenting a WordPress product! Before I started using it, I tried a couple other plugins for creating meta boxes but, once I found the excellent user-experience and AMAZING documentation provided with ACF, I became hooked and haven’t looked back. What makes ACF’s documentation so top-notch is that Elliot Condon, the developer of Advanced Custom Fields, has a full page dedicated to each field type (i.e. checkbox, repeater, etc.) and API function, all of which include detailed explanations of usage, both from a regular user’s perspective and a developer’s. For developers, he’s included information about what types of parameters functions accept, what they return and excellent code examples.

Gravity Forms

Coming in at a close second is Gravity Forms, the most popular (and amazing) form builder plugin for WordPress. The power of Gravity Forms is astounding and the documentation is excellent. Like ACF, it includes information on how to use the plugin as a non-coder and as a developer. The developer documentation also includes explanations of parameters and return values, as well as code examples. The only reason I put Gravity Forms behind ACF is because I know there are a few very helpful parts of the API that are not documented (hopefully they will be).

Easy Digital Downloads & WooCommerce

While these two have solid documentation, they aren’t quite on the same level as ACF and Gravity Forms. I lump them together even though they’re different plugins because their documentation is about the same (each has its advantages over the other, though). They both include very good instructions on regular usage and they also provide decent developer documentation. However, the reason I think they fall behind the other two is in this developer documentation area; there are so many great features to the code that are not documented in any way and are only discovered when digging into the code. Now I don’t mind stumbling across things in the code, especially if the code is well commented with details about parameters, returns, etc. I’d prefer, though, a full front-end resource for developer documentation like with ACF or GF, as it would make my life a lot easier.

Wrapping Up

As someone who appreciates excellent documentation as much as I appreciate awesome functionality, I wish documentation was more of a collective priority in the WordPress product-development market. There are products with superb documentation (i.e. Advanced Custom Fields and Gravity Forms) and there are products with absolutely no documentation. I understand that writing documentation is nowhere near as fun as writing the code but the documentation will serve as a voucher and learning tool for your product. If you are serious about your product, please document it.