Welcome to the MetaMetaMeta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. Team!
The Meta team is responsible for maintaining and managing WordPress.orgWordPress.orgThe 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/ websites. Our work is mostly done on the meta trac. If you see a bug, file a ticket!
Recently some of us on the MetaMetaMeta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. team did some experimenting with hypothetical changes to the WordPress Developer Docs, especially the function reference. As developers and frequent users of the docs, we’re aware of its shortcomings and potential for improvement. In order not to risk breaking anything and give ourselves freedom to make significant changes, we forked the codebase into an experimental repo.
The changes we came up with turned out to be quite solid and sensible, and I think most of them are good enough for production. Since they were made as unilateral experiments, we’d like to hear feedback from the +make.wordpress.org/docs/ team and community in general as to what should happen next. You’ll find an outline of some of the most notable changes below.
A local development environment
We started by setting up a fresh repository with a fork of the necessary code, including the Handbook pluginPluginA 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, phpdoc-parser, and the current theme. The repo contains a complete local Docker environment, so you can run a copy on your local machine to develop and test changes. The local environment imports function reference content by parsing phpdocs just like in production; and it also imports some handbook content from GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/. It doesn’t import all handbook content, but there’s enough for testing purposes.
Here’s a typical function reference page you’ve probably seen before: get_posts(). I’ve highlighted some of the more visible things we changed:
After much discussion and experimenting, we decided to remove the TOC entirely from function reference pages. It still exists on handbook pages, where it’s more useful because the heading structure of those pages is much more variable.
Updated designs and better parsing help in surfacing the right information – quickly. See #31, #49, #65.
6. Inline code looks like code
Inline code is highlighted in more places, like within the parameter section. #97.
7. Expand array arguments that are described on other pages
Some WordPress functions don’t fully document their $args arrays, when those parameters are passed through to another function. The expanding $args array feature saves you from having to click through to another function to read the details:
Here’s what it looks like when you click to expand the More Arguments summary:
8. Return syntax highlighting
The Return section now uses syntax highlighting for clarity. #39.
9. Clearer language
Some links in the old docs take you to surprising places. We made them more obvious. #62.
10. A new syntax highlighter
We switched from the old SyntaxHighlighter Evolved plugin to Code Syntax BlockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience., which is based on the Prism.js library.
The colour scheme has been kept close to the original, but the new one is more accessible and works in more places. #44, #85.
11. Code buttons
The UX for copying code from the old syntax highlighter, and expanding/collapsing large blocks, was inconsistent. We made it clearer and more accessible. #79, #100, #106.
12. A new HooksHooksIn 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. section
Instead of burying them in the Uses section, we made a whole separate section for hooks with a unique design. #28, #32.
13. A more useful Uses section
As well as moving hooks out to a separate section, we hid the most common WordPress functions from the Uses section, so it now gives a less cluttered view of calls used by the current function. #37.
But that’s not all!
We also made plenty of other changes that aren’t shown above.
Did you know you can oEmbed a function reference page in any WordPress post? You could before, but it wasn’t very useful. We improved the design, and made it work for classes too. #59, #102, #112.
Consistent site titles
We updated the site title to be “Developer Resources” for all the handbooks (excluding dashicons) to make navigating consistent within the theme and the rest of WordPress.orgWordPress.orgThe 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/. Read more.
Now we can also click on a large icon to link to the target page, rather than having to aim for the text.
We also made various other changes improving the design, UX, and accessibilityAccessibilityAccessibility (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). You can see all of our merged PRs here.
I can see three basic paths forward:
Do nothing. If the changes here are too controversial, that might be the best option.
Merge selected changes into production. That’s the way forward if only some of these changes are suitable to go live.
Move the entire repo to production. If all of the changes are suitable, or if only a few small reversions are needed.
Moving the entire repo into production is probably easier than backporting selected PRs. It would also give us the local development environment, which makes community development and testing much easier going forward (as with Learn and the Pattern Directory for example). But, since we made all these changes unilaterally, it’s up to the Docs team and community in general to decide how to proceed.