WordPress Developer Docs Showcases New Blocks-Based Remodel – WP Tavern

WordPress Developer Docs Showcases New Blocks Based Remodel – WP Tavern

Over the years, the WordPress developer documentation, originally the Codex but now the WordPress Code Reference, has served the project well. However, there is a feeling in the community that much of the recent documentation, such as the JavaScript APIs and packages that have come out of Gutenberg, has been inconsistent and harder to read and understand. Developers often navigate disconnected designs and organizations in various documents, guides, and tutorials for topics that can range from the Shortcodes API to WP-CLI.

Last December, the entire Developer Resources subdomain of WordPress.org was relaunched with a much more intuitive homepage, consistent navigation, and a modern design. In developer circles and on social media, the reboot received rave reviews as well as more than a few sighs.

Screenshots of the Developer Resources homepage after and before the redesign.
Then and before. Source: make.wordpress.org

Although the redesign appeared almost three months ago, it belongs to WP Tavern as a modern WordPress project benchmark. I caught up with Automattic-sponsored Developer Advocate Nick Diego to learn more about the story behind the transformation and what else we can expect from WordPress.org's multi-year migration to a new look and feel.

Defining the scope of the project

If you've seen Nick's name recently, it might be from his popular WordPress plugins like Block Visibility and Icon Block, or his work on the WordPress Developer Blog. The team of contributors running the Developer Blog have been busy educating readers on how to work with the many new and experimental tools coming out of Block Editor. But some of them are also deep in the trenches trying to rewrite developer resources with twenty years of legacy, like Justin Tadlock's ongoing work with the Theme Handbook.

“One of my team's big focuses,” explained Nick, “is to try and improve the Block Editor Handbook and the Themes Handbook. And so we're working on the content of it, and there's still tons of work to do, but one of the things we discovered early on was that the structure and design of the site just made things worse.” (I'll spare readers the links to my many tweets and podcasts on that very topic).

READ  How to set up your Mac with WordPress to develop a news site like ours

When they realized this, the team faced a choice. They could have just ignored the outdated design issues and continued to update the content. They could completely overhaul how the project's developer documentation was structured and start a massive rebuild. Or they can continue to work within the existing architecture, but focus on cleaning up obvious design gaps.

They chose that third approach, focusing on redesigning what they had rather than trying to defend an entirely new document platform. It also freed up more time to continue updating the most important part, the content.

“I'd rather spend my time fixing (the content),” Nick explained. “Because if we ever get to a point where we want to rebuild the whole thing, it's an architectural problem and not an 'oh, and all our content is wrong problem.'

The team began working on modernizing the content and design, and Nick was able to use his expertise to help with the recent redesign of the storefront on WordPress.org.

Documents by contribution

An important caveat to the WordPress documentation is that it is also open to implementation, just like WordPress core. That means the structure where documents are written, discussed, and posted should be accessible to any contributor who can help.

Some of the documentation, like the Theme Manual, actually lays out the WordPress installation content. Nick explained that “it's really hard to contribute because you can't go somewhere and write a pull request. You have to open an issue that says, “Oh, there's a typo here,” or “Oh, this paragraph needs to be changed,” and then some document contributor who has permission goes in and commits it. It's a fierce challenge.”

If a team wants content to be collaborative, it ultimately needs to have some connection to GitHub, where collaboration tends to happen. The advantage of this approach is that developer documentation can become an opportunity to become a WordPress contributor. Once you do a small pull request to fix a typo, it becomes a bit easier to think of a PR as an actual code change.

READ  Tumblr and WordPress Strike Deals to Sell Public User Data to AI Giants OpenAI and Midjourney

“So we have some parts of the site (on WordPress),” Nick said. “We have some pieces that are on GitHub. There are other parts that are generated from source code, other parts that are part of packages. So it's a very complex setup where there's content in a lot of different places, and even with stuff on GitHub, it's coming from a lot of repositories.”

Any documentation currently on GitHub has an “Improve it on GitHub” link in the signature, which takes you to its source.

Learning from building block topics

Updating the developer documentation site to match the new design language being shared on WordPress.org meant moving it from a classic theme to the same underlying block-based parent theme that all newly redesigned WordPress.org sites use. What some might have seen as an insurmountable challenge, this team saw as an opportunity for learning and “testing”.

“The documentation section is huge,” Nick said, “How do you keep it updated on the block theme? So we also looked at it as a project where Meta would learn a lot in the process.”

The team can take all their experience of moving a massive website—hundreds of pages of content, some of which is authored within WordPress, but most of it populated by automated integrations with multiple GitHub repositories—and share the lessons they've learned with the core team. which was building the Site Editor itself.

One example that I'm sure any developer will resonate with was the issue of block theme version control.

“Everything in dot org needs version control,” Nick explained. So the Site Editor works, but then you have to sync all changes to the theme's template files. So there are definitely some challenges that the Meta team has had to work around due to the unique requirements of dot org. But it was a really interesting case study.”

READ  Hackers are using a WordPress plugin flaw to infect 3,300 websites with malware

Nick and his colleagues then used their expertise to facilitate discussions on GitHub with the wider community of developers who are also facing these very issues with block themes.

The conversion is in progress

The transformation of WordPress.org is a multi-year effort with many concurrent projects. A few that Nick and his colleagues are focusing on next include redesigning the rest of the WordPress Documentation, an end-user facing content area known as HelpHub, along with the Forums and Templates directory.

Along the way, their focus is making sure the community is aware that these redesign projects are all public to review and engage with.

Nick added, “Figma is public, GitHub is public, but is it as public as it could be from a visual community perspective? No. And I think that's something we're trying to do better. So we're trying to improve the process so that it's more visible going forward.”

The team is more active in posting updates on the Make WordPress blog as well as a dedicated Slack channel: #website-redesign. The ultimate goal of these redesigns is to increase the quality and accessibility of information, as well as to make it easier to contribute to the project.

“One of the things that we've actually seen,” Nick said, “is that when the redesign happened and it got a little bit more attention and people started using it, then the UI issues kind of disappear, and then you start seeing problems with the content, which leads to more people fixing the content.”

If you're interested in contributing to the design or content of some of these upcoming projects, consider joining the WordPress Slack or following the Make WordPress blog.

Leave a Reply

Your email address will not be published. Required fields are marked *