Documenting The WordPress Plugin Boilerplate

October 7, 2014

A little over a month ago, I released the latest version of the WordPress Plugin Boilerplate. The response has been great – more than I was expecting, really but that’s a good thing – and, generally speaking, it’s been overall positive.

The WordPress Plugin Boilerplate Homepage

Over the last month or so, it’s become clear that more time and resources will be needed to focus on the Boilerplate and to continue to refine its codebase, its functionality, its documentation, and so on. The bottom line is that I want to make sure that I get the right – or as close to right – as possible during the first try.

To that end, I need some input from others (read: you).

Docs (and More) For The WordPress Plugin Boilerplate

Right now, the Boilerplate’s homepage is a single landing page linking to a GitHub repository or a direct download. Though I’m happy with the state of that right now, though it’s never been my intent to leave it as that; however, since it’s a side project and we only have so many hours to which we can devote to those types of projects, I was planning on holding off until January 2015 to focus on adding more material, documentation, and so on.

It’s becoming clearer that that’s a bit far out in the future or some. Instead, more needs to happen faster, though this is going to require additional resources. Thankfully, the latter isn’t a problem: I’ve had a number of people already volunteer their time to help with various aspects of the Boilerplate and I’m grateful for that.

At this point in its development, however, I’m being very cautious with any pull requests, changes, or even recommendations. I consider them all but I want to make sure that I’m staying true to the original idea behind the project and that I’m not just merging in various requests with no rationale or behind it.

Sometimes, this means things are merged; other times, it means that we have a discussion in the comments on GitHub until something has been decided.

Read The Manual

Right now, the number one thing that needs to occur is that documentation needs to be written. Code comments are not enough (and were never intended to be), but in order for the Boilerplate to be as big a resource as it can possibly be, then we need explanations of the following:

The purpose of each file

An explanation of the organization of the files (to better understand how to follow it with future cases)

Example code for how to achieve common tasks

…and more

All of the above need to be done in a very polished way to help make sure that the Boilerplate is as accessible to a beginner as it is to an intermediate (or even advanced) programmer. This means that there will need to be a site dedicated exclusively towards this.

I’m willing to write the documentation for the project (and have been all along) since it initially started out as my own and I was part of the core decision-making. While planning to write the documentation, I’ve been planning to setup a a separate WordPress installation and use a theme that serves as a basis for a manual.

I question that there’s enough information to warrant an actual blog. But this leads me to ask: Should there be an entire blog dedicated to the Boilerplate, or do the general updates on this site work just as well? If so, what would you expect from a blog about the project?

And Then What?

Obviously, documentation is the number one priority for the project as it’s meant to help explain how everything fits together and how to best use the Boilerplate as it stands.

But what comes next?

That is, once the documentation is written, what would be most helpful in using the actual project? Right now, I know others would like to see:

Example code showing how to achieve common tasks like creating a custom post type

Code generators for easily replacing all of the various TODOs

Grunt-compatible versions,

…and much more

To this point, I’ve been open about the project and it’s progress and though I’d love for everything to move faster, the reality is that I can only move as fast as time allows (which varies month-to-month, of course), but that doesn’t mean that we can’t focus on prioritizing other things in order to create a roadmap of sorts for this project.

So what would you like to see and why?

From here, I’m hoping to take the feedback and begin organizing how to best proceed, and perhaps grab a few people to help with the tasks. Before that, I’d like to get them outlined.

Join the conversation! 30 Comments

Hi Tom, I would love to see some walkthroughs/Video Tutorials. I have watched pretty much everything you have created on tutsplus regarding wordpress and have learnt so much from those. I always like having some documentation to refer to but I find nothing more informative than watching the code flow from the creator.

I would love to see some walkthroughs/Video Tutorials. I have watched pretty much everything you have created on tutsplus regarding wordpress and have learnt so much from those.

This is a great idea – thanks! I have something coming up with WP Sessions early next year, but I think having small videos that are available would be good (after all, we’ve different styles of learning, right?).

I always like having some documentation to refer to but I find nothing more informative than watching the code flow from the creator.

Thank you Tom for your efforts. I’ve never written a plugin before but I already have a couple of ideas for one and really didn’t want to start with a blank page :-) When I’m ready I will be using this tool.

I hate that I’ve never developed a plugin and to be honest I’ve been wanting to do one for so long. This is clearly where I need to start. I just looked at it and I’m really excited. Hopefully I will have some feedback as well. Thanks for your hard work on it :)

Code examples! Common plugin scenarios and how they would best be handled using the WPBP would be fantastic! Obviously, with a bit of explanation as well. I also found your articles on tutsplus super helpful and relevant to the boilerplate. So having similar examples and explanations will go far.

Second that! Examples are always most helpful. I’m also looking forward to the documentation that explains the purpose of each file. I’ve been working with the wppb just yesterday and everything works really nice :)

I feel that the examples are important, but primarily some links to good documentation and already existing tutorials on the subject could be a great help and a good quick way to start. If I had a get-started document or blog post/page that discussed the gist of things, and under every topic link to applicable docs on wordpress.org or other good resources, then we cover a lot of ground without having to re-invent the wheel all at once. Then it would be great to build upon that with the examples and screencasts etc.

I say this because obviously WordPress is documented, and if you even just inline linked within the files to related/corresponding sections/files docs then I have somewhere to go to get started and can see the idea as I go. I could google this stuff, but there’s a lot of stuff to sift through. So if you can do this, then it saves me a lot of time and I can get right into the details.

I also do feel that a blog would be a great resource once there are enough people to contribute to it. I said people – yes. If you can approve select people to write for this, then perhaps when they get an idea or come up with example projects they can walk you through, then they can just post it. I could see it becoming a great tool. Posts all the time, the likes of “how to build a widget plugin that shows custom data from posts”, and “how to build a simple slider plugin”, or “how to build a plugin with custom post types and customized forms for data entry.”

It could go on and on. It’s when we as individuals get to understand those basic building blocks that we can find our creative paths to make those blocks into a unique form.

I vote for documentation over a code generator. In particular, I would love to see some examples of common design patterns – custom post types, widgets, admin menu, ajax handler etc – and I would like to see them all in the same plugin so we can see an example a large plugin that contains many classes with many hooks.

I’m in the process of refactoring one of my plugins and I’m a little unsure about the loader. Is it correct to pass the loader around to all the class constructors? eg: new My_Plugin_Name_Module( $this->loader )

Just to add to that. I’m wondering if there could be a separate folder on GitHub for ‘common design patterns’ or something like that? Then developers could submit code ideas via pull requests. I would love to submit code examples and get feedback on best practice.

Code Generators are something that will be shared (and some people have already written them).

I also plan to share various patterns and what not for exactly what you’ve described. It’ll take some time, but having these suggestions is a big help because it makes sure that I’m collecting all the ideas for what to include :).

Another vote for having real-life examples – custom post types, ajax request, hooks, options page, metaboxes, widgets…The Boilerplate is really cool, but without examples it is close to impossible to use for someone with just a basic WP OOP plugin development – I developed many plugins using procedural code, but I’m really lost in the Boilerplate – questions like “Should I create a new class for this?” or “How should the class actually be loaded” pop all the time.

Hi Tom, Great work – this will be a fantastic resource for plugin developers wanting to get started with a good solid base to build on. Theres so many different ways to code WordPress plugins that a Rails style “Convention over configuration” approach could help a lot.

I’d really like to see an example plugin or two in the docs as well though, really showing how to actually add other code on top of this.

Also, could I suggest adding a page to the Github Wiki called “Showcase” or something similar, where people can add plugins which have been created on top of the Boilerplate ?

I’d really like to see an example plugin or two in the docs as well though, really showing how to actually add other code on top of this.

This is arguably one of the top requests that I have for the Boilerplate, so this is something that I’m definitely going to be doing.

Also, could I suggest adding a page to the Github Wiki called “Showcase” or something similar, where people can add plugins which have been created on top of the Boilerplate ?

Yes and no. I’m trying to stay away from GitHub as much as possible other than for source control and issues because it’s not very beginner-friendly, but I am definitely looking to introduce a showcase page for all of the plugins that are built using the Boilerplate.

Just Getting Started with WordPress?

I write a lot about WordPress development but if you're just getting started, I recommend checking out WPBeginner. They have free training videos, glossary, and more.

WPSessions hosts some of the best WordPress training you’ll find anywhere from many well-known speakers.

If there’s something you’d like to learn, and it’s not already covered here, it’s probably been covered at WPSessions. If you use the special link below you can watch your first session for free and get a steep discount on the full-access VIP membership.