Introducing the New Block-Based Redesign in WordPress Developer Docs
WordPress, one of the leading content management systems, has recently launched a new block-based redesign for its developer documentation. The previous documentation, known as the Codex, had served the project well over the years. However, there was a growing sense in the community that the more recent documentation, particularly related to JavaScript APIs and packages from Gutenberg, lacked consistency and was harder to comprehend.
In December, WordPress.org’s entire Developer Resources subdomain underwent a relaunch, featuring a more intuitive homepage, cohesive navigation, and a modern design. The relaunch was met with enthusiasm from developers and received rave reviews. It marked a significant milestone in the WordPress project.
To gain more insight into the story behind the redesign and the future plans for WordPress.org’s migration to a new look and feel, I had the opportunity to speak with Nick Diego, a Developer Advocate sponsored by Automattic.
Nick and his team recognized the need to improve the Block Editor Handbook and Themes Handbook, two crucial resources for developers. They also identified that the structure and design of the existing site were hindering their efforts. Rather than advocating for an entirely new documentation platform, they decided to focus on redesigning the existing one while continuing to update the content.
By updating the content and design simultaneously, Nick drew on his experience from the recent redesign of the Showcase on WordPress.org. This approach allowed them to allocate more time to fixing the content itself, ensuring that it was accurate and up to date.
One challenge faced by WordPress documentation is its open contribution system. Just like WordPress core, the documentation is open to contributions from anyone. However, this posed difficulties as contributors were required to open issues for minor changes or errors instead of making direct pull requests. The team recognized the need for a more collaborative approach and aimed to connect the documentation process to GitHub, where collaboration usually occurs.
The team also leveraged their experience with block themes to update the Developer Documentation site. They migrated it from a classic theme to a block-based parent theme, aligning it with the new design language of WordPress.org. This served as a learning opportunity for the team and allowed them to share valuable insights with the core team responsible for building the Site Editor.
The redesign of WordPress.org is a multi-year project, with various concurrent projects taking place. The next focus for Nick and his colleagues includes redesigning the rest of the WordPress Documentation, the HelpHub, Forums, and the Patterns Directory. Throughout the process, the team aims to ensure that the community is involved and informed about these redesign projects.
To increase visibility, the team has been actively posting updates on the Make WordPress blog and maintaining a dedicated Slack channel. The ultimate goal of these redesigns is to improve the quality and accessibility of information while facilitating contributions to the project.
Since the redesign, more attention has been drawn to the content itself, leading to increased efforts in fixing any issues or errors. This highlights the positive impact of the redesign on community engagement and collaboration.
If you’re interested in contributing to the design or content of these upcoming projects, consider joining the WordPress Slack or following updates on the Make WordPress blog. The WordPress.org redesign presents an exciting opportunity for developers and contributors to shape the future of WordPress documentation and enhance the overall user experience.
