The WordPress Theme Handbook has a lot of great content from numerous contributors over the years. It is filled with wisdom and experience learned from their trial, error, and work. For everyone who has volunteered their time to build this resource: thank you.
The problem with handbooks for ever-changing software is that they need a large re-tuning from time to time. The Theme Handbook has reached that point in its lifespan.
It was created during a time when classic themes were the only method of front-end design for WordPress. Much of its content now exists in a transitory state between classic and modern block 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. theming. This has created a scenario where the handbook sometimes reads more like patchwork than if it were built with a single vision. That is often a natural result of adding new documentation over years.
The following is a proposal to give the Theme Handbook the refresh that the theming community deserves.
A New Handbook
Over the past several weeks, I have created an initial outline of what the Theme Handbook could look like. This was based on an analysis of the current content in the handbook and Codex and early feedback from the handbook reps. The outline is also forward-looking with the goal of creating a guide for theme creators in the coming years.
Read the outline document →
I want to stress that this outline is a starting point, a way to get some movement on the proposal. It is not set in stone. The goal is for the theming community to reshape it into something that helps everyone, including both first-time creators and seasoned developers. We may end up with something entirely different from the current outline document.
This proposal is to overhaul the entire Theme Handbook. That means that no idea is too “crazy” during this stage. So, dream big and share your vision for what the handbook should be in the comments below.
With that in mind, it is important to set some dates and not leave this so open-ended that nothing moves forward. Therefore, the feedback period for the outline ends on April 28, 2023. That provides nearly a four-week period for us to work alongside each other to create an outline for a new theme handbook.
The outline proposal will be on the agenda for discussion during the Themes Team meeting on April 11, 2023 at 15:00 UTC.
There will also be a dedicated meeting on April 18, 2023 at 13:00 UTC via the #themereview channel on Slack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.. Everyone is welcome to join and discuss this proposal in detail.
Questions and (Some) Answers
How do I participate in the outlining process?
There are currently four ways to get involved:
- Leave a comment on this post with your feedback and ideas.
- Discuss during the Themes Team meeting on April 11, 2023 at 15:00 UTC via the #themereview Slack channel.
- Join us for the outline proposal meeting on April 18, 2023 at 13:00 UTC via the #themereview Slack channel.
- Make suggestions directly in the Google Doc for the outline.
What are the next steps after the outlining process?
In the upcoming meeting, we can start to define the next steps on following through with this proposal. This should include, at least, a new ticket on the Documentation Issue Tracker with an overarching plan.
Who will create the content for the handbook?
We all will. The Theme Handbook is and has always been a community project. The more people involved, the better the resource is for us all.
What will happen to existing content?
There is no reason to remove the content the handbook already has. There is a lot of great material there that we should carry forward. Some of it might need to be updated or reorganized, but that can be tackled during the next step. The goal at the moment is to primarily improve the overall outline and flow of the handbook.
Why are Classic Themes in a single chapter?
The goal of the outline was to explore the handbook from a modern perspective and one that will best serve creators in the coming years. It makes sense that the focus of the handbook should be on block theming, especially now that the Site Editor is out of beta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process.. Block themes are the present and future of WordPress.
The outline also makes room for all of the existing content to be migrated to appropriate sections, much of it under a dedicated Classic Themes chapter. Classic theming isn’t disappearing, but the current handbook often makes for confusing reading jumping back and forth between classic and block theme examples.
Like the rest of the outline, this is 100% open for discussion.
What happens to permalinks with the current handbook?
I don’t have an answer for that yet. It would certainly be a part of whatever the final proposal becomes. Some ideas that have been thrown around so far have been a redirect solution or to create a “v2” of the handbook with the old version being archived in much the same way as the Codex still exists. I also don’t think that is a major concern until the outline is finished. It may be easier to simply incorporate new sections/pages into the existing handbook. Whatever the case, it’s best not to let this discussion deter us from creating a new vision.
In other words: let’s cross that bridge when we come to it.
Will there be a new design?
The handbook designs are outside the scope of the Themes and Documentation teams. The Design team has been routinely sharing what many of the pages of an upcoming redesign will look like via the #design-share tag. There is a definite need for a full overhaul of the design that works well for documentation-style pages. Anyone interested in that aspect should visit the Get Involved page of the Design Team handbook.
Props to @poena, @kafleg, and @juanmaguitar for their feedback on this proposal.
#theme-documentation
