Exploration: improving DevHub

Recently some of us on the MetaMeta Meta 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 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, 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 GitHubGitHub GitHub 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.

Visible changes

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:

And below the fold on a function like wp_authenticate():

1. Better search 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.

We moved the search box and improved the UX.

2. Better code signatures

We made it easier to see the return type and linked the type for easy navigation.

3. Removed the TOC

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.

4. Better anchor links

Anchor links now match the design of handbook pages.

5. Better parameters

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 BlockBlock Block 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 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. 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.

Better embeds

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.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/. Read more.

Improved Search autocomplete

It’s now more obvious whether you’re searching for a function or a hook:

Icons on the home page are clickable

Now we can also click on a large icon to link to the target page, rather than having to aim for the text.

Other changes

We also made various other changes improving the design, UX, and 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). You can see all of our merged PRs here.

What’s next?

I can see three basic paths forward:

1. Do nothing. If the changes here are too controversial, that might be the best option.
2. Merge selected changes into production. That’s the way forward if only some of these changes are suitable to go live.
3. 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.

Comments are welcome here, and if you’d like to test out the experimental code yourself with Docker and Yarn then please feel free to report and discuss issues.

cc +make.wordpress.org/docs/ +make.wordpress.org/core/

#docs #devhub