Handbooks: Theme & Plugin Developers

After discussion with a few people, and looking through some material that’s been sent to me, I’m thinking it may be better to separate the theme/pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party development handbooks out from the other, more contributor- focused handbooks. This will let us get a greater level of detail into the theme/plugin dev handbooks. However, I would still like maintain consistency across these two handbooks. Both Chip and Brad sent me through some ideas, and by looking through both of them, I came up with this loose structure that I think we can fit things into.

Introduction
Tools
Part 1: The Basics (how themes/plugins work)
Part 2: Requirements (what you must include in your plugin/theme)
Part 3: Functionality (different functionality available to you and how to implement it – should include working examples)
Part 4: Settings & Options (creating and using options, the settings APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.)
Part 5: Security (how to stay secure, data validation)
Part 6: Best Practices (UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing., UXUX UX is an acronym for User Experience - the way the user uses the UI. Think ‘what they are doing’ and less about how they do it., AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility), general best practices)
Part 7: Releasing your Plugin/Theme on WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/
Part 8: Glossary

If you’re planning to work on the plugin or theme development handbooks I’d appreciate if you could just let me know what you think of that schema, and tell me whether there is anything that you think won’t fit into those chapters.

The other thing to note, is that these two handbooks will take much longer than the shorter contributor handbooks to complete. I’m going to publish a timeframe and dates later this week, and we’ll plan for a longer time frame on these two.

Let me know what you guys think.

#handbooks

Chris Reynolds 2:53 pm on December 17, 2012

My only thought is that I wonder if the Best Practices section would even be needed, considering we’ll probably be covering all that as we’re writing the other documentation. I don’t know that there would be anything left to go into that assuming all the other sections were written with best practices in mind.
- Pippin (mordauk) 3:07 pm on December 17, 2012
  
  I’d say best practices should definitely be included. Even when you show examples that illustrate best practices, that doesn’t necessarily make people understand exactly how or why to use them.
Pippin (mordauk) 3:09 pm on December 17, 2012

I’m happy with that structure.
Drew Jaynes (DrewAPicture) 8:51 pm on December 17, 2012

The structure looks pretty good.

One thing that may just fit under best practices is things you can do to support your users. It’s not just about maybe subscribing to the RSS feedRSS Feed RSS is an acronym for Real Simple Syndication which is a type of web feed which allows users to access updates to online content in a standardized, computer-readable format. This is the feed. for your theme/pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party forum but providing meaningful documentation. I’ve seen @ipstenu rail time and again on Twitter about bad readme files. I think there’s a need to educate new (and experienced) ‘extend’ authors on how you can help your users help themselves.
jhoffm34 9:14 pm on December 17, 2012

Really like the structure, but I know that we mentioned there might be some crossover between the two groups in the Google Hangout last week. Looking at this, it seems that there might be even more. Requirements will start the same (dev. environment) then sort of branch off from there. Definitely some security crossover and maybe some best practices, in addition to some of what we talked about last week. But maybe I’m overthinking it?
- Chris Reynolds 10:58 pm on December 17, 2012
  
  I wouldn’t worry about the security and best practices crossover. I’m sure there will be some (nonces, data validation, etc) but it would probably be a slightly different context. And we need to assume that people reading the theme handbook aren’t going to be reading the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party handbook and vice versa. Development environment would definitely be similar, but that may be as far as that goes for the requirements. “Requirements”, to me, for theme development would be like, you need to have an index.php and a style.css. For a plugin it could be, you need to have the plugin headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes..
  - jhoffm34 2:16 am on December 18, 2012
    
    All good points. Guess I was underthinking it. Thanks Chris!
Tom McFarlin 9:55 pm on December 17, 2012

I like the structure for the handbooks, Siobhan. Good stuff.
Rachel Baker 2:32 pm on December 18, 2012

Siobhan,

Thumbs up for your very well thought-out and organized structure.

Great work.
Gordon Guthrie 8:05 am on February 22, 2013

The biggest single pain is the lack of a master diagram showing the major phases of loading and constructing a page as a cycle, ie first we start preparing the page and the following hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. are called, then we build the page headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes., and the following hooks, then we build the etc…

Once you under the cycle then it is pretty easy to plug things in, but with understanding the cycle, you randomly search and then stick in an action and suck it and see…
- Siobhan 9:37 am on February 22, 2013
  
  If you’d like to stick a diagram together that would be excellent. It would be really useful to have that sort of overview.

Want to get involved?

Weekly meetings

Handbooks: Theme & Plugin Developers

Want to get involved?

Weekly meetings

Share this: