Theme Handbook Overhaul (Tracking Ticket)

[justintadlock]

In April, there was a proposal to overhaul the WordPress Theme Handbook with a new structure and learning pathways for theme creators. April 28 was the deadline for feedback on the proposal. After two meetings and an open discussion, we have an outline that we can begin working from.

To reference the progress on this project, visit the following docs and posts:

• Handbook Outline (Google Doc)
• Theme Handbook Overhaul Proposal
• Themes Team Meeting Notes (April 11, 2023)

Tracking Issues

This is an overall tracking ticket for the project. The following list should be updated to link to specific tickets as they are created. The list may also be amended as this project progresses. Note that some pages already exist and merely need to be moved or potentially updated.

• [ ] Welcome to the Theme Handbook
• [x] Chapter 1: Getting Started
  • [x] #1257
  • [x] #841
  • [x] #845
  • [x] #847
  • [x] #852
  • [x] #878
• [x] Chapter 2: Core Concepts
  • [x] #1258
  • [x] #920
  • [x] #921
  • [x] #930
  • [x] #969
  • [x] #984
  • [x] #989
  • [ ] Tools and resources
• [x] Chapter 3: Global Settings and Styles
  • [x] #1123
  • [x] #1122
  • [x] #1003
    • [x] #1084
    • [x] #1049
    • [x] #1050
    • [x] #1061
    • [x] #1066
    • [x] #1078
    • [x] #1121
    • [x] #1099
    • [x] #1092
    • [x] #1093
    • [x] #1108
    • [x] #1098
    • [x] #1111
    • [x] #987
  • [x] #1117
    • [x] #1118
    • [x] #1119
    • [x] #1120
  • [x] #1113
  • [x] #1124
  • [x] #1116
  • [x] #1112
• [x] Chapter 4: Templates
  • [x] #1125
  • [x] #1126
  • [x] #1128
  • [x] #1132
  • [x] #1130
• [ ] Chapter 5: Patterns
  • [x] #1519
  • [x] #1478
  • [x] #1479
  • [x] #1480
  • [x] #1483
  • [x] #1486
  • [x] #1505
  • [x] #1518
• [x] Chapter 6: Features
  • [x] #1134
  • [x] #1141
  • [x] #1138
  • [x] #1135
  • [x] #1142
• [ ] Chapter 7: Classic Themes
  • [ ] Chapter Landing Page
  • [ ] #1357
  • [ ] Templates
  • [ ] The Loop
  • [ ] #1358
  • [ ] Conditional tags
  • [ ] Theme functionality
  • [ ] Theme options / the Customizer
  • [ ] Plugin API hooks
• [ ] Chapter 8: Advanced Topics
  • [x] #1417
  • [x] #1383
  • [x] #1404
  • [x] #1377
  • [x] #1361
  • [x] #1412
  • [x] #1370
  • [x] #1359
  • [x] #1409
• [ ] Chapter 9: Accessibility
  • [ ] Chapter Landing Page
  • [ ] Principles of accessibility
  • [ ] Block themes
  • [ ] Resources
• [ ] Chapter 10: Guides
  • [ ] Chapter Landing Page
  • [ ] Building With Create Block Theme
  • [ ] Migrating a classic theme to blocks
  • [ ] #1419
  • [ ] #1418
• [ ] Contributing

[github-actions[bot]]

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

[zzap]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[justintadlock]

There was a new page recently published on Theme Security: https://developer.wordpress.org/themes/theme-security/theme-security-issues/

This would fit into the upcoming Security page from this outline, but I think some of that needs to be added as part of the split/move to the Make Themes handbook (particularly, things that are specific to the DotOrg directory).

[javiercasares]

I'm going to add me more work here :P but... do you need help to have this handbook like the plugin one on GitHub? There is a ticket pending to move it to the WordPress organization, but we should create this documentation as Markdown.

I can help move it from Google Docs to a GitHub repo if it works for you.

[justintadlock]

@javiercasares - I'd love to have a dedicated GitHub repo for managing this. It would save a lot of headaches with moving content around. It's something @richtabor and I recently discussed that would help contributors keep things updated.

I'm personally fine helping to move the content over to Markdown in a repo, and we can certainly start drafting upcoming docs in Markdown.

CC: @kafleg, @carolinan - Thoughts?

[javiercasares]

We've been working on this with @zzap for some projects (The Advanced Administration, a year ago, the Plugins with the plugins team a couple of months ago -working on finishing the transition-), so, it's a good opportunity to plan it.

There are 2 good things behind this:

• autosync with the developer site (everything in the "main" will be synced automatically every 15 minutes
• start working on the internationalization project, so we can have all the documentation in a lot of languages.

[justintadlock]

@javiercasares - You mentioned a pending ticket. Can you share that link? That'd probably be the best place to discuss anything we need to do on our end. And I can update the instructions in this ticket for drafting new docs when this moves forward.

For existing Google Docs, there's not many that would need to be moved to Markdown. It's just the open tickets above (under the Classic Themes and Advanced Topics sections). All of the other closed tickets have now been moved to develop.wordpress.org/themes.

[javiercasares]

• DevHub Plugins Team (developer.wordpress.org/plugins) Handbook sync
• Plugins Team (make.wordpress.org/plugins) Handbook sync