I hope everyone had a good break over the holidays. I know I caught up on some much-needed rest and am now excited to get back into the swing of doing fun things with WordPress themes.
Now it’s time to discuss the current progress and next steps of one of our biggest projects of 2024: the Theme Handbook overhaul.
What Is the Theme Handbook Overhaul?
This is a project that the theming community agreed to take on last year. Its goal was to give the Theme Handbook content a refresh, primarily focusing on modern block theme development.
You can read the initial proposal and previous project updates here:
- Initial Proposal
- Theme Handbook Overhaul: Phase 2 (Creating Content)
- Theme Handbook Overhaul: Phase 3 (Publishing Content)
The ongoing work is tracked via the Theme Handbook Overhaul tracking ticket on GitHub.
The Project’s Progress
In 2023, five new/updated chapters were published in the handbook:
The primary focus of these first five chapters is to introduce theme creators to the block theming system. Most of this documentation is 100% new. If you haven’t browsed the handbook for a while, now is a great time to catch up!
There are also eight draft articles that have yet to be published.
In terms of “chapter count,” that’s nearly half of the project. But if looking at the actual new content that needed to be created, it’s probably closer to 2/3 of the way toward the finish line.
The Next Steps
The plan is to complete the entire overhaul by the end of Quarter 2 (June 30) of 2024. I believe we can get the bulk of the new content published or drafted in Q1, leaving most of Q2 for final touches and cleanup.
In the coming months, there are still six chapters left to create or update:
- Patterns (recently added to the outline)
- Classic Themes
- Advanced Topics (mostly drafted)
- Accessibility
- Guides
- Contributing
The Classic Themes, Advanced Topics, and Guides chapters are mostly content updates and a bit of reorganization. These are what I’d call “good first issues” for anyone who wants to contribute but is not ready to write a full documentation article on their own.
The Patterns chapter was recently added to the outline because patterns are a first-class tool in WordPress that will only continue to become more powerful. There is currently a single Block Patterns doc, but it needs to be expanded into multiple articles that showcase each pattern feature. If you like to tinker with patterns, this could be a fun chapter to contribute to.
One area where the project really needs a volunteer is for the Accessibility chapter. It’d be great to have an expert in the field to review and expand upon the existing documentation.
Get Involved
To get involved, all you need to do is:
- Find a topic without its own ticket from the outline in the Tracking Issue.
- Create a new issue (select the New Doc Request option) in the Documentation Issue Tracker repository with the `Themes` label for your chosen topic.
You can reach out for help with this in the #docs or #themereview Slack channels. You can also ping me (@greenshady) directly if you have questions.
Props to @kafleg for reviewing this post.
