Who: @milana_cap, @mkaz, @utz119
When: Dec 8, 2021 @ 1500 UTC
What:
We met to discuss the upcoming block themes in WP 5.9 and where to document with relation to the existing Theme handbook.
Summary:
Block themes has a small call out as an experimental feature now on the first page of the Theme handbook. The next step is to update that page with a clear distinction between Classic themes and Block themes, a brief explanation about the differences, and links to learn about each. Classic themes links will continue to theme handbook, Block theme links will go to Block editor handbook.
Discussion:
We discussed what current documentation we have between the two handbooks. The ongoing goal will be to highlight the areas of overlap between classic and block themes and keep those in the handbook, try not to duplicate any documentation in either handbook, and use plenty of cross links so developers can find what they need.
We touched on some complexities with the Block editor handbook structure. The initial goal was teaching developers about blocks, getting them started learning and creating blocks. We need to look at information architecture and flow of the handbook to better help developers navigate. For with WP 5.9 features like block themes, theme.json, styles and settings a developer can be greatly involved with topics covered in the handbook without having to create a block.
A larger project that needs to be tackled is the information architecture of all developer handbooks and documentation. Valuable content is being created and organized in various different areas in different ways, this makes it hard for developers to find what they need. For example, great developer content is created within Learn that is not cross-linked with developer.wordpress.org. Additionally, browsing the “Common API” or “Code Reference” sections only return the PHP APIs when there is a large suite of JavaScript APIs in the Block editor handbook.