On April 4, there was a proposal to overhaul the WordPress Theme Handbook that would bring the documentation more up to date, create a new structure, and be more inviting to first-time theme creators.  Since then, the Themes Team has held two meetings where the proposal could be discussed:

• April 11 team meeting (notes)
• April 18 handbook meeting

The meetings and open discussion on the proposal post provided an opportunity for everyone to discuss the initial outline (Google Docs link) for the new handbook. Based on feedback over the past month, this outline has largely stayed the same with a handful of adjustments. Thank you to everyone who participated in these discussions and helped shape it into what it is today.

The next steps

Now that we have solidified the overall new handbook outline, it is time to start moving forward with the next steps. The following lays out a plan to tackle actually reshaping the handbook into something new.

This is the part where the project could really use your help! The more people involved with creating content, the more successful this endeavor will be.

Source of truth: GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ ticket

The Theme Handbook Overhaul Tracking Ticket will serve as the primary location to track and manage the overall progress of this project. 

Essentially, this ticket will list all of the chapters, pages, and sections that need to be created or updated. 

Creating tickets

See something you want to work on? Create a new ticket in the Documentation Issue Tracker (be sure to read the Contributing Guidelines). Once a ticket has been created, we can add it to the primary tracking ticket. 

Creating content

The current plan is to build the new handbook within the existing handbook, moving and adjusting things as necessary. Once most or all of the work is done, the old menu will be replaced with a menu that reflects the updated structure.

As you create content for a specific issue, it will eventually need to be added manually to the Theme Handbook. Because this is an entire overhaul of the handbook, some new pages may need to wait for other pages to be written before they go live. Decisions on how best to handle this may happen on a case-by-case basis.

Reshaping the outline

While we have a pretty solid outline at the moment, things tend to change when you actually get into creating the content of the project. Sometimes things need to be rearranged, added, or changed in some other way. That is not an issue at all, and we can address those situations as they arise.

AccessibilityAccessibility 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)

The new handbook structure proposes a larger Accessibility chapter. Any contributors who are well-versed in a11yAccessibility 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) are definitely needed for this project’s success.

When will the project be complete?

A realistic goal is likely the end of Quarter 3 of 2023. This can be adjusted as needed, but it helps to have a deadline to shoot for. 

With that said, the handbook will never truly be “complete.” Documentation is a living, breathing creature that needs continual care. Even when the initial overhaul is finished, there will always be the need for contributors to continue making it better.

Get involved

If you would like to contribute, just head over to the tracking ticket and find a sub-ticket that needs to be worked on or create a ticket for a handbook page that has yet to be created.

Props to @poena and @kafleg for review.

#theme-documentation