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.

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.


We had a meeting about formatting style and…

We had a meeting about formatting, style, and other general handbook stuff.

In attendance: Me, Japh Thomson, Aaron Osteraas, Tom McFarlin, Ryan Imel, Curtis McHale, Bradley Jones, Chris Reynolds, Dougal Campbell (briefly), all the randoms on Google Plus who felt like dropping by.

I’m afraid that I didn’t manage to record it. But here’s what we discussed:

1. Review of the schema
Consensus was that it looks good.

2. Review of current WordPress writing tips
We’re happy with these and I’ll make a copy of them for the docs blog.

3. Tone and voice
We agreed that a consistent tone of voice would be good throughout. This is a discussion to have between content people like me and any branding/marketing people who would like to get involved. At the minute WordPress does have a style and tone but there’s nothing written down.

4. Formatting
Formatting is good. We’d like some styles that can be applied to call-out boxes within the text. For the following:

  • Info
  • Tip
  • Important

5. Tools

Tools we would like to use:

  • Syntax Highlighter Evolved
  • Edit Flow

Since there are about 45 people involved, it would be useful to have a P2P2 P2 or O2 is the term people use to refer to the Make WordPress blog. It can be found at https://make.wordpress.org/. for this project. If not on .org I’ll set one up on .com

We acknowledged that there could be issues with code snippets and moving back and forth between the visual and text editors. Therefore we thought about turning off the visual editor.

We also discussed looking at https://wordpress.org/extend/plugins/wp-markdown/

6. Workflow
I provided an overview of the workflow and schedule. Everyone seemed happy enough with this. We agreed that we should have staged deadlines throughout the project. I will post about this later in the week.

7. Other issues

Duplicate content
We acknowledged that there could be issues with duplicate content. We discussed the possibility of delivering generic content with using an ajax link, however this would mean that content would have to be generic. In the end we decided to aim for a better reading experience for the user, rather than making content too generic. However, we should be aware of when content might be duplicated elsewhere and tag it as so.

Also, if content is similar – such as setting up SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. for plugins/themes/coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., then if it is written in one place it can be used as the base for articles elsewhere.


We would like to have a lovely design for the handbooks. The layout and formatting should be the same for each handbook, but each one should be its own colour.

Expect an update about workflow and schedule later this week.


Pedants of WordPress Unite! (aka a handbook update)

Do you love to worry about oxford commas? Do you care about whether you write in the first, second, or third person? Do formatting considerations keep you up at night? Then this is your opportunity to get your voice heard!

It would be great to achieve consistency across the handbooks, so I’d like to have a discussion about content style and formatting. As a result, we will have a style guide. The style guide is something that I hope that writers will be aware of, but it will be particularly important for editors and proofreaders, so if you do want to work on editing any of the manuals, or want to proofread, please do come along. Also, anyone else who is interested is more than welcome.

Let’s do this in a Google Hangout.

Tuesday 11th December @ 2100 UTC (that’s 9pm London) – here’s the time everywhere else.

You can find me on G+


1. Review of the schema:
I’d just like to make sure everyone is happy with it and it is fit for purpose.

2. Review of current WordPress Codex writing tips:
Are they suitable for the handbooks and shall we generate a style guide from them?

3. Tone and voice

4. Formatting

heading usage, screenshots, use of bold, call-out boxes

5. Assessment of any additional tools needed
Syntax highlighter etc

6. Brief discussion of workflow
I’m going to write a post up about this – the idea will be to get started with actual content creation in the New Year. But I’d love to discuss some ideas with you guys. If necessary we can schedule another chat about it.

At some point I’d also like to have some 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) guidelines drawn up. For example, the best way to make use of alt tags, and making sure we create a structure that’s accessible.

If there’s anything else that needs discussed, please add it to the comments.

[update: yes – I did originally title the post “pendants of WordPress unite”. This is why we need people like you!]