In April 2023, there was a proposal for overhauling the Theme Handbook, which included an initial outline of what a new handbook might look like. After two public meetings to fine-tune the details of the outline and discuss the project, we moved on to Phase 2. This phase meant writing the new content for the handbook.
Since then, the work has been tracked on GitHub. Now it is time to step into the next phase of this project, but first:
A progress update
The overarching outline for the new handbook is:
- Welcome to the Theme Handbook
- Chapter 1: Getting Started
- Chapter 2: Core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Concepts
- Chapter 3: Global Settings and Styles (theme.json JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.)
- Chapter 4: Templates
- Chapter 5: Features
- Chapter 6: Classic Themes
- Chapter 7: Advanced Topics
- Chapter 8: Accessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility)
- Chapter 9: Guides
- Contributing
Thus far, chapters 1-3 (Getting Started, Core Concepts, and Global Settings and Styles) are near completion. That may not seem like much in comparison to the whole, but these are some of the heaviest chapters, at least in terms of new content that must be written.
Much of the content from the Classic Themes and Guides chapters already exists (plus a few docs from the other chapters). They may simply need to be reorganized based on the outline.
Publishing content in Phase 3
In the coming weeks, we should start bringing new content into the handbook, starting with Chapter 3: Global Settings and Styles. Then, as Chapter 4: Templates, Chapter 5: Features, and beyond are written, publish them when ready.
Why skip over the first two chapters?
The first two of the new chapters, Getting Started and Core Concepts, cannot be moved to the handbook until more of the later chapters are published. The primary reason for this is because they are learning pathways to more advanced topics. This means that they have a lot of links to content that hasn’t been written/published yet.
Later chapters are much more self-contained. This means that they can go live without having to wait for all of the new handbook content to be written first.
So both Phase 2 (Creating Content) and Phase 3 (Publishing Content) will now be running simultaneously.
Any help reviewing the current drafts, particularly under Chapter 3: Global Settings and Styles, would be very helpful as we kick-start this next phase. Check out the tracking ticket for the individual tickets.
Phase 4 and beyond
It’s still a little too early to get into the final phase of this project. But once we move most of the new content along, we will discuss how to proceed with the final migration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. to the new handbook and any remaining cleanup.
My hope is that we have a new Theme Handbook by the end of 2023. I’m certain there will be continued work, things that we missed, and new features on the horizon. The handbook should be a living document, forever evolving alongside WordPress. This project is as much about setting a foundation for the future as it is revamping the current handbook.
Props to @kafleg for feedback and review on this post.
#theme-documentation
