Saying “here’s how to write a plugin” is far too general. It gives no frame of reference for what you’re going to be covering, what the plugin is going to do, what the prerequisites are, or what the end result is going to be. It may even get a beginner’s hopes up only to let them down to leave them feel more confused by the time they’re done.

Saying “here’s how to write your first WordPress plugin” is a little bit better because it sets a level of expectation in terms of the level of experience required. If the reader is a new developer or if they are an experienced developer, it’s still going to be teaching them how to work within the confines of WordPress. Sure, there are a multiple ways to write plugins but learning how to get started is the first step towards seeing that. 

Saying “here’s how to write a plugin that will read user profile information using the WordPress API to create a unique author page” is clear. It explains exactly what it’s going to do and lays out the different points of WordPress that will be used in the tutorial. 

Even if the reader doesn’t know it yet, the author knows that, when putting something like this together, s/he is going to need to use a combination of:

  • templates or template parts,
  • the ability to read user metadata with the API,
  • safely render information from the backend to the frontend, and how to handle all of the checks in between to make sure nothing is passed up from the database to the frontend that doesn’t need to be or that’s something like an empty value.

Further, there’s an opportunity to to highlight some other best practices like sanitization, escaping, maybe internationalization, etc. All of that would be content for another article, but teasing it out can help.  And this is speaking from experience.

So why bring all of this up?

Continue reading