Educate Your Users in Open Source Software

One of the things that I’m working hard to have released by the end of the month is the latest version of the WordPress Plugin Boilerplate.

The latest version has been in development for quite a while now (a lot has happened offline so, you know, that’s how it goes).

The last time that I really spent any time talking about this project was in November 2013. A lot has changed since then. Initially, I was planning on a minor upgrade with some of the following features:

  • Releasing the version has part of the 2.x.x versioning
  • Including a class specifically for administrative functionality
  • Fixing issues with symbolic links and textdomains
  • Including more TODO’s for users to find what needs to be changed
  • …and so on.

But when I got started on the next version of the Boilerplate, a lot of things changed. The short of it is that it’s being completely re-written from the ground up and the code and documentation are being split into to separate things for the sake of user education.

I’ll spend more time talking about the Boilerplate in a future, but one of the things that I wanted to share that’s related to running a project like the Boilerplate has to do with open source, contributions, lack of a vision, and how this can negatively impact your project and your users.

Educate Your Users (Do Not Do Their Work)

In a previous series of posts, I’ve shared my thoughts on Open Source Project Management. Being that it’s a series of posts, it’s obviously covers a lot of information, but over the past few months while working on the Boilerplate, I’ve struggled quite a bit as it relates to what should or shouldn’t go into an iteration of a project.

Work to educate all of your users.

Work to educate all of your users.

Through both experience, reading, and chatting with my team (Ulrich, Josh, and Brad), I’d like to think I’ve gotten a bit better at triaging tickets, ideas, maintaining a vision, and working towards keeping things within a well-defined scope.

TL;DR

The short version of everything that I have to share is this:

If you offer too much functionality into a boilerplate-style code, people are going to ask for more, and more, and more, and more until your Boilerplate becomes a bloated piece of code that people are looking to do in order to copy, paste, and get going. They aren’t looking to learn. 

Walk that line very finely. Educate your users, but don’t do their work for them. 

This is something that I think is far easier to talk about than to actually practice. When I read articles and posts about people managing open source projects that are far, far larger than anything I have worked on (or probably ever will work on), I can’t help but respect their skills at keeping a project on track.

But that’s just the TL;DR.

Of Course, I Have More to Say

Obviously, one of the larger projects that I see this being well-managed is WordPress itself. Though this isn’t a post about WordPress explicitly, I do believe that keeping the course towards a specific release can be a very challenging thing and watching those who have lead development for past and current releases is something to admired.

To make it worse, some can get near irate of there’s a ticket that they fully believe should be part of a core update rather than a piece of documentation and they will be quick to let you know, or to make a lot of noise about it.

"But I need this feature and I can't build it!"

“But I need this feature and I can’t build it!”

But just as that’s the prerogative, so is the ability of a development lead to reject ideas, tickets, or triage things for a future release.

Here’s the thing:

  • Though a project may be open source, that doesn’t mean that it’s open to every suggestion.
  • Though a project may be open source, that doesn’t mean it’s open to the vision of every single person who uses the software.
  • Though a project may be open source doesn’t mean that it’s open for deviations from a core purpose.

To be clear, this is not to sound ungrateful to project contributors because any time someone volunteers their time (that is, their most valuable resource) to something you’re working on, it’s humbling.

At the same time, this doesn’t mean that you have to be a “Yes man” or a “Yes woman” to all things that come into the request queue for the project.

With that said, the next iteration of the WordPress Plugin Boilerplate is going to be tagged 3.0.0 and it’s a total rewrite of the entire project. There are a lot of changes that are coming to this version of the Boilerplate, as well – some are going to like them, some aren’t.

And that’s cool with me.

I’d like to think that the overall plan behind the next version of the Boilerplate is going to help developers – specifically beginner to intermediate developers – write object-oriented-based code with greater ease and understanding.

As I said above:

Educate your users, but don’t do their work for them. 

To do that, this means that a lot of the initial code that’s included in the Boilerplate is already commented and describes what’s happening. The README file is trimmed down, and there’s far less needed to do to get up and going if you’re more along the lines of an experienced developer.

But what about those who are just getting started?

Rather than trying to mix the educational material in with the documentation for the code along, we’re breaking the project and it’s educational aspect into two parts:

  1. The core code will be available on GitHub.
  2. The documentation, examples, frequently asked questions, and more will be on the project’s website.

Though there’s a lot to be said about the following from a software design standpoint, ultimately the point of splitting the source code away from the documentation is for the point of education. Those who are comfortable with object-oriented programming, writing WordPress plugins, and the coding standards will have everything they need to start working on their plugin by downloading the code in the repository.

Those who aren’t as familiar with the aforementioned things but still want to get started are going to have a resource that’s available to them for reading more about why things are the way they are, and how to achieve what they want.

I think that this not only will get us away from the copy and paste mentality that permeates the underbelly of open source software and tutorials, but will also provide a significantly better experience for anyone who is looking to get started.

This weekend, I spent sometime triaging tickets that have been sitting in the project’s issues queue for sometime (read: months, even). Some of the tickets have been solved, some of them are irrelevant because of the new code organization, some of them remain unsolved, and some of them will not be solved – at least not in code.

Instead, where the Boilerplate was once an all-encompassing project that mixed documentation and code in an attempt to provide a single stop for developers to get started with their work, it also grew into a larger code base with code that’s not relevant to a general WordPress installation, that was difficult to understand for those who are just looking to get started, and arguably required more to be removed than to be added for creating a plugin – at least some of the time.

That’s exactly the thing I wanted to move away from with the latest version. So thus, the split in code and documentation.

Furthermore, and trying to bring everything full-circle, triaging the tickets that have been sitting in the queue brought clarity has to how far the codebase has come, what the website should include, and how to empower and educate users on writing maintainable WordPress plugins.

I know that as the project continues to move forward, additional tickets are going to be created (which is awesome), and feedback – both positive and negative – is going to be given. My biggest goals with this next version include doing a better job of educating those who will be building plugins, but also maintaining a consistent vision for the project.

Wait, a New Site?

As far as the new features, organization, and site are concerned, I’m eager to show you but will do so in a future post.

11 Comments

Awesome news about a new version of the Plugin Boilerplate, even though I just finished moving to the current version. :P

One thing that I struggled with somewhat was the separation of PHP from HTML in the views, especially as it related to populating drop-downs. I think I did a decent job of it, but couldn’t help wondering if there was an even better way. I’d love to see some tips on this in the documentation.

Cheers and thanks for the boilerplate, both for plugins and widgets.

    One thing that I struggled with somewhat was the separation of PHP from HTML in the views, especially as it related to populating drop-downs. I think I did a decent job of it, but couldn’t help wondering if there was an even better way. I’d love to see some tips on this in the documentation.

    This is one of those things that different people have opinions on (and I’m no different).

    As the Boilerplate is released and the documentation becomes more full with answers to FAQs, I’ll show how to do certain things like this as well as an explanation behind the rationale for it.

I am an experienced LAMP developer, just getting into WP plugin development. At the 2014 WordCamp Kansas City, Pippin Williamson pointed me to your plugin tutorial. I’m about half-way through it (and moving to a new house at the same time), and it’s great. I am very interested in your BoilerPlate project. When you say “by the end of the month”, do you mean that BoilerPlate 3.0.0 should be out before September 1? That would be perfect for me, because I’d just as soon not get invested in the old version, when 3.0.0 seems so great. Count me as waiting with anticipation.

This is good news, the boilerplate will come in handy especially for us who are looking to dive in more to plugin development, at least now will have something updated with latest WordPress conventions to work with. Thanks so much for your contribution to the WordPress community..:)

thanks for thinking of others. looking forward to 3.0.0.

Thanks for thinking of us, less skilled. I will look forward to be educated. :)

Leave a Reply

Name and email address are required. Your email address will not be published.

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>