WordPress Developer Docs Shows Off a New Block-Based Redesign – WP Tavern
Through the years, WordPress’s developer documentation, initially the Codex however now the WordPress Code Reference, has served the mission properly. Nonetheless, there’s been a way in the neighborhood that a lot of the newer documentation- for instance, the JavaScript APIs and packages popping out of Gutenberg- has been inconsistent and tougher to learn and perceive. Builders typically discover themselves navigating disconnected designs and group all through the assorted docs, guides, and handbooks for matters that may cowl something from the Shortcodes API to WP-CLI.
This previous December, WordPress.org’s entire Developer Resources subdomain relaunched with way more intuitive homepage, cohesive navigation, and a contemporary design. In developer circles and on social media, the relaunch was met with rave critiques, together with various sighs of aid.
Though the redesign appeared virtually three months in the past, it belongs within the WP Tavern as a contemporary milestone for the WordPress mission. I caught up with Nick Diego, a Developer Advocate sponsored by Automattic, to study extra concerning the story behind the redesign and what else we are able to count on from WordPress.org’s multi-year migration to a brand new feel and look.
Defining a Venture Scope
When you’ve seen Nick’s title lately, it might be from his well-liked WordPress plugins, comparable to Block Visibility and the Icon Block, or else his work on the WordPress Developer Blog. The crew of contributors operating the Developer Weblog have been busy educating readers on methods to work with lots of the new and experimental instruments popping out of the Block Editor. However a few of them are additionally deep within the trenches making an attempt to rewrite twenty years of legacy developer assets, like Justin Tadlock’s ongoing work with the Theme Handbook.
“One of many huge focuses for my crew,” Nick defined, “was to attempt to enhance the Block Editor Handbook and the Themes Handbook. And so we’re engaged on the content material of it, and there’s nonetheless tons of labor to do there, however one of many issues we recognized early on was that the construction and the design of the positioning, it simply made issues worse.” (I’ll spare readers the hyperlinks to my quite a few Twitter and podcast rants on that actual matter.)
As soon as they realized this, the crew was confronted with a selection. They might merely ignore the problems with the outdated design and proceed updating content material. They might utterly rethink the best way that the developer documentation for the mission was constructed and begin an enormous restructuring. Or they might hold working throughout the current structure however deal with cleansing up the obvious gaps in design.
They selected that third strategy – specializing in redesigning what they’d, reasonably than making an attempt to advocate for a wholly new documentation platform. That additionally freed up extra time to proceed updating a very powerful half: the content material.
“I might reasonably spend my time fixing [the content],” Nick defined. “As a result of then if we ever get to some extent the place we wish to re-architect the entire thing, then it’s an architectural drawback and never an “oh, and all our content material’s all fallacious drawback’.”
The crew started work on updating the content material and design in tandem, and Nick was in a position to attract on his expertise serving to out with the current redesign of the Showcase on WordPress.org.
Documentation by Contribution
One vital caveat for WordPress documentation is that it is usually open to contribution, identical to WordPress core. That signifies that the construction wherein documentation is written, mentioned, and hosted must be accessible to any contributor who may have the ability to assist.
Among the documentation, just like the Theme Handbook, is definitely publish content material inside a WordPress set up. Nick defined that “it’s actually laborious to contribute to, as a result of you may’t go write a pull request someplace. You must open a difficulty that claims, ‘Hey, there’s a spelling error right here’ or ‘Hey, this paragraph ought to be modified’ after which some docs contributor that has permission used to go in and make it. It’s wildly difficult.”
If the crew needs content material to be collaborative, it in the end must have some connection to GitHub, the place collaboration tends to occur. The profit to this strategy is that developer documentation will be an onramp to changing into a WordPress contributor. When you’ve made a small pull request fixing a spelling error, it turns into a bit simpler to think about making a PR with an precise code change.
“So now we have some items of the positioning [in WordPress],” mentioned Nick. “We’ve got some items which might be on GitHub. There’s different components which might be generated from supply code, different items which might be a part of packages. So it’s a really sophisticated setup the place there’s content material in so many alternative locations, and even with the stuff that’s in GitHub, it’s coming from a number of repositories.”
For now, any of the documentation that does stay on GitHub has a hyperlink to “Enhance it on GitHub” within the footer, taking you to its supply.
Studying From Constructing Block Themes
Updating the Developer Documentation website to match the brand new design language rolling out throughout WordPress.org meant migrating it from a basic theme to the identical underlying block-based parent theme that all the newly redesigned WordPress.org websites are utilizing. What some may see as an insurmountable problem, this crew noticed as a studying and “dogfooding” alternative.
“The documentation part is big,” mentioned Nick, “How do you replace that to a block theme? So we additionally checked out it as a mission the place Meta will study rather a lot as the method goes.”
The crew might take all of their experiences of migrating an enormous website- a whole lot of pages of content material, some authored inside WordPress however a lot of it populated by automated integrations with quite a few GitHub repositories- and share the teachings they’d study with the core crew that was constructing the Website Editor itself.
One instance that I’m certain any developer will resonate with was the problem of model management for a block theme.
“Every little thing in dot org wants model management,” Nick defined. “So the Website Editor works, however then you need to sync all of the modifications again to the template recordsdata within the theme. So there are undoubtedly some challenges that the Meta crew have needed to circumvent due to the distinctive necessities of dot org. Nevertheless it’s been a extremely attention-grabbing case research.”
Nick and his colleagues then used their expertise to facilitate discussions on GitHub with the broader developer group who’re additionally grappling with these actual points with block themes.
The Redesign Continues
The WordPress.org redesign is a multi-year endeavor with quite a lot of concurrent tasks occurring. A number of that Nick and his colleagues are targeted on subsequent embrace redesigning the rest of the WordPress Documentation, a phase of end-user-facing content material often known as the “HelpHub”, together with the Forums and the Patterns Directory.
Alongside the best way, their focus is on ensuring the group is conscious that these redesign tasks are all public to assessment and have interaction with.
Nick added that “Figma is public, the GitHub’s public, however is it as public because it might be from a visible perspective throughout the group? No. And I believe that that’s one thing that we’re making an attempt to do higher. So we’re making an attempt to enhance the method so it’s extra seen shifting ahead.”
The crew has been extra proactively posting updates on the Make WordPress weblog in addition to in a devoted Slack channel, #website-redesign. The top aim for these redesigns is to extend the standard and entry to info, but additionally to make contribution to the mission simpler.
“One of many issues that we’ve really seen,” mentioned Nick “is that after the redesign occurred and there was a bit extra highlight on it and other people began utilizing it, then the issues with the UI type of go away and then you definitely begin to see issues with the content material, which ends up in extra individuals fixing the content material.”
When you’re excited about contributing to the design or the content material of a few of these upcoming tasks, contemplate becoming a member of the WordPress Slack or following alongside within the Make WordPress blog.
