Expanding and solidifying curation pathway documentation

[annezazu]

Overview

Building on work shipped in July 2022 to document various curation pathways, I believe we're at a stage in where we need individual docs for each pathway with detailed examples, links to Learn WP resources, and quick WordPress Playground links to experience the change.

To be clear, this is talking about the various ways one can lock down and curate the experience of using WordPress, especially with the introduction of more design tools and full site editing functionality.

Aim: Have dedicated docs with live playground links about each curation pathway to help improve adoption of these features and ultimately the Site Editor.

Problem to discuss: How do we find the best "home" documentation wise for each individual doc? Ideally, in the future this doc https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/ just becomes a list of docs for each individual resource that lives across both the theme and block editor handbook.

Kicking off the discussion here as folks have thoughts and feedback about what they'd like to see and where each should live.

Current Format

A single document with the following top line and sub headers:

Locking APIs

• Lock the ability to move or remove specific blocks
• Lock the ability to edit certain blocks
• Apply block locking to patterns or templates
• Apply content only editing in patterns or templates
• Change permissions to control locking ability

Providing default controls/options

• Define default options

Limiting interface options with theme.json

• Limit options on a per block basis
• Disable inherit default layout
• Limit options globally

Limiting interface options with theme.json filters

Limiting interface options with client-side filters

Remove access to functionality

• Remove access to the template editor
• Create an allow or disallow list to limit block options
• Disable pattern directory

Utilizing patterns

• Prioritize starter patterns for any post type
• Prioritize starter patterns for template creation
• Lock patterns
• Prioritize specific patterns from the Pattern Directory

Combining approaches

Proposed Format

Each of the following would be individual pages that are then link to from the overall handbook page:

• Lock the ability to move or remove specific blocks
• Lock the ability to edit certain blocks
• Apply block locking to patterns or templates
• Apply content only editing in patterns or templates
• Change permissions to control locking ability
• Define default options
• Limit options on a per block basis with theme.json
• Disable inherit default layout with theme.json
• Limit options globally with theme.json
• Limit interface options with theme.json filters
• Limit interface options with client-side filters
• Remove access to the template editor
• Create an allow or disallow list to limit block options
• Disable pattern directory
• Prioritize starter patterns for any post type
• Prioritize starter patterns for template creation
• Lock patterns
• Prioritize specific patterns from the Pattern Directory
• Combining approaches

^ The key is figuring out where each of these should belong since, for example, there's great overlap in terms of providing patterns with themes.

Each individual page would include at least one example or demo video, like for locking blocks in the UI. Ideally, these will each all have WordPress playground instances that will allow folks to both see the code and see the code in action to understand more about what it does.

[carolinan]

My first thought is to use the training team's repository for code examples, that @justintadlock recently brought up in #themereview slack channel: https://github.com/wptrainingteam/block-theme-examples

This could be used together with or even replace the individual pages.

[annezazu]

Agreed! I'll open issues in that repo for some of these examples that are already on my mind.

[unscripted]

@annezazu Thanks for putting this list together. I definitely agree with the challenge being where to place this info since it could apply to multiple locations.

I like @carolinan 's suggestion as a place to build the example code but would recommend linking to those examples from the individual pages.

A few questions:

• Could we define "curated pathways" in this PR description? This name isn't intuitive to me as I view these as customizations or restrictions. When I hear curation, I think of collecting and organizing. Maybe this is a curated list of customizations?
• Do you have a vision for the page hierarchy template? If we're able to identify the critical sections needed, we can pattern the issues for each page with acceptance criteria to make sure we're addressing those items.
• Do you envision moving the existing content into the sub-pages as is or switching to sub-pages only once they've been rewritten? I can see a benefit to moving as is, because we could then link to the new pages in the issue for each item.

[unscripted]

For page hierarchy, it could be cool to do something similar to the USWDS components pages.

• Overview
• Visual example w/ link to playground.
• Guidance
  • When to use the feature
  • When to consider something else
  • Usability guidance
  • Accessibility
• Using the feature
• Additional Resources

[annezazu]

Could we define "curated pathways" in this PR description? This name isn't intuitive to me as I view these as customizations or restrictions. When I hear curation, I think of collecting and organizing. Maybe this is a curated list of customizations?

Updated the overall issue description.

Do you have a vision for the page hierarchy template? If we're able to identify the critical sections needed, we can pattern the issues for each page with acceptance criteria to make sure we're addressing those items.

For some reason (it could be end of day brain), I am struggling to understand what you mean here. Can you restate? Very generally, I'd like to see the following structure for each sub page:

• Description of approach.
• Use cases/when it makes sense to try this approach.
• Code example(s).
• Playground link to explore when applicable.

How does that sound to you/does this answer your question? This also impacts two initiatives underway to overhaul the block editor handbook and theme handbook so I want to be very mindful in getting feedback from the folks working on both of those.

Do you envision moving the existing content into the sub-pages as is or switching to sub-pages only once they've been rewritten? I can see a benefit to moving as is, because we could then link to the new pages in the issue for each item.

I envision moving as is and then building out personally, unless anyone objects :) Curious to hear more of what you think.

[unscripted]

Thanks, @annezazu!

Regarding the page hierarchy, you nailed what I was looking for. I think what I was envisioning was a separate issue for each section that needed to be addressed. Then then each issue could be structured to make sure the page hierarchy was consistent on publish.

Below is an example issue from WordPress/Learn than is similar to the issue pattern where each acceptance criteria can be checked off.

WordPress/Learn#1735

My biggest driver for patterning the issues and crafting acceptance criteria is to drive consistency if there are multiple contributors. It also makes it a bit easier for the tester(s) IMO.

Thanks for taking this on. All the disparate docs have definitely been a challenge for our team as we're sometimes on the bleeding edge of FSE. I know you said you'd be taking this on personally, but I'd be happy to contribute where you need assistance.

[annezazu]

My biggest driver for patterning the issues and crafting acceptance criteria is to drive consistency if there are multiple contributors. It also makes it a bit easier for the tester(s) IMO. Thanks for taking this on. All the disparate docs have definitely been a challenge for our team as we're sometimes on the bleeding edge of FSE. I know you said you'd be taking this on personally, but I'd be happy to contribute where you need assistance.

Ah! I see. Thanks for clarifying in turn. I'd love to get your feedback as these docs start shifting and coming to life in a new way. I agree that we can add a bit more structure to this issue as it evolves. For now, I was hoping to have a discussion to see what, if any, strong feelings or thoughts came out before jumping in to break up each item :D

To aid this effort and get more on the same page with folks already doing work in both handbooks (theme and block editor), I had a chat with @ndiego @justintadlock and @juanmaguitar and I wanted to recap here how we can iteratively move forward. Let me know what you think?

Proposed iterations

V1: Divide and solidify

Break each logical section into individual pages (locking APIs, providing default controls/options, etc) and add in more content/links to articles/video that we already have from the Developer Blog (no new content!).

Timeline: ~next month
Owner: @ndiego

V2: Incorporate playground examples

Build and include block theme examples into curation pathways in the block theme examples repo as suggested by @carolinan above.

Timeline: next 1-2 months for first pass.
Owner: @justintadlock

V3: Dedicated pages

Start getting dedicated pages for each individual pathway in each section (filters in plugin, everything else is theme) and have set format (description, code, link to code & live demo) that is influenced by lessons learned with block development examples like this.

Timeline: 3+ months/TBD
Owner: TBD.

[unscripted]

This is awesome.

[annezazu]

Update: V1 is done thanks to @ndiego quick work 👏🏼 #57289

[annezazu]

Closing this out as https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/ is fairly robust at this point and a new issue should be created to continue to have it evolve.