Improving the learning journey of WordPress Playground in the Docs

[juanmaguitar]

Some contributors (including @ryanwelcher, @justintadlock, @ndiego, @bph and myself) met with @adamziel to discuss ideas to improve Playground docs.

The following list is a set of suggested actions based on the ideas discussed in that meeting. Please, feel free to add your comments to shape any of these actionable items.

• New structure for introductory sections at https://wordpress.github.io/wordpress-playground/

  • Introduction 🔗 /wordpress-playground - Adapted content from current one at /wordpress-playground
  • Quick Start Guide 🆕 🔗 /wordpress-playground/quick-start-guide - Adapted content from current one at /start-using
  • About WP Playground 🆕 🔗 /wordpress-playground/what-is - new page with current content at /overview
    • include here WordPress Playground Vision and Philosophy or maybe create a new section at the end (after "Architecture") for Vision and Philosophy
  • WP Playground for developers 🆕 🔗 /wordpress-playground/for-developers - new page with content adapted from /wordpress-playground/build-your-first-app
  • WP Playground tools 🆕 🔗 /wordpress-playground/playground-tools - new page with a map of content of current Local development
    • wp-now NPM package 🆕 🔗 /wordpress-playground/playground-tools/wp-now - current content at /wordpress-playground/local-development/wp-now
    • VS Code extension 🆕 🔗 /wordpress-playground/playground-tools/vscode-extension - current content at /wordpress-playground/local-development/vscode-extension
    • php-wasm/node 🆕 🔗 /wordpress-playground/playground-tools/php-wasm-node - current content at /wordpress-playground/local-development/php-wasm-node

• Provide entry points for different user profiles

  • From Handbooks
    • Plugin Handbook Create a new section called WP Playground for plugin developers 🆕 🔗 /plugins/playground-plugin-developers - highlighting all the WP Playground info relevant to plugin developers (steps blueprints, demos...)
    • Theme Handbook Create a new section called WP Playground for theme developers 🆕 🔗 /plugins/playground-theme-developers - highlighting all the WP Playground info relevant to theme developers (steps blueprints, demos...)
    • Block Editor Handbook Create a new section called WP Playground for block developers 🆕 🔗 /plugins/playground-block-developers - highlighting all the WP Playground info relevant to block developers (steps blueprints, demos...), although the guide at plugin handbook may be enough
  • From Playground docs
    • There will be links to guides at different handbooks and any others that can be included in the Guides section

• Highlight/surface links to Docs from different resources related to WP Playground

  • https://playground.wordpress.net/
  • https://wordpress.org/playground/
  • https://github.com/WordPress/wordpress-playground
  • and different tools powered by WP Playground

• Blueprints 🔗 /wordpress-playground/blueprints - Include here (merge contents) Blueprints 101 course

  • Use the Blueprints Gallery into the docs as examples of each step (i.e., “Blueprints 101”).

• Guides 🆕 🔗 /wordpress-playground/guides - create new section with misc guides interesting for users (according to feedback received and questions from the community

[ironnysh]

Hi @juanmaguitar, thanks for sharing. I'm happy to help any way I can.

A few questions:

• This outline seems focused on extenders (i.e., developers 🙂). How about creating/repurposing resources for other audiences, like designers, educators, and end users?
• What would happen to the sections that weren't mentioned here (the APIs, architecture, contributing, etc.)?
• The restructure would affect the content only, or is there a plan to change the technical setup as well?

[juanmaguitar]

Hi @ironnysh, to clarify, this issue is intended to start introducing only a few ideas to improve the WP Playground Docs. It may evolve, incorporating some more ideas, or maybe those ideas could be addressed on other issues.

This outline seems focused on extenders (i.e., developers 🙂). How about creating/repurposing resources for other audiences, like designers, educators, and end users?

I think there could be specific pages addressed to different profiles under the proposed "Guides" section. As per "End Users" I think the suggested "Quick Start Guide" (current "Start using WordPress Playground in 5 minutes") would be a good introduction to start using Playground to any user

What would happen to the sections that weren't mentioned here (the APIs, architecture, contributing, etc.)?

Those sections could be addressed after further analysis. There are several issues across different repos WordPress/blueprints-library, WordPress/wordpress-playground, WordPress/Documentation-Issue-Tracker so I see some work to do to coordinate all the proposals and suggestions already made to improve the Playground docs.

The restructure would affect the content only, or is there a plan to change the technical setup as well?

AFAIK any suggestions to improve any tool powered by WP Playground are more than welcome. If there's something already on your mind, please feel free to open an issue with your thoughts to any of the playground-related repos:

• WordPress/wordpress-playground
• WordPress/blueprints-library
• WordPress/playground-tools

[ironnysh]

Thanks, @juanmaguitar!

There are several issues across different repos WordPress/blueprints-library, WordPress/wordpress-playground, WordPress/Documentation-Issue-Tracker so I see some work to do to coordinate all the proposals and suggestions already made to improve the Playground docs.

100% :-) Doing some triage would be very helpful.

change the technical setup

Sorry, I meant the Docs stack: right now, it's Docusaurus on GitHub, but @adamziel has been experimenting with a different workflow.

[juanmaguitar]

Sorry, I meant the Docs stack: right now, it's Docusaurus on GitHub, but @adamziel has been experimenting with a different workflow.

Oops, sorry, I didn't catch that well 😅
Yes, I think another setup for WP Playground docs involving WordPress and a contribution workflow involving Playground itself (like this one) should be a goal for Playground Docs. But this discussion probably belongs in a different GH issue.

[ironnysh]

Got it 👍

[adamziel]

Thank you @juanmaguitar!

This outline seems focused on extenders (i.e., developers 🙂)

there could be specific pages addressed to different profiles under the proposed "Guides" section. As per "End Users" I think the suggested "Quick Start Guide"

I agree with @ironnysh – the new structure seems focused on developers. We do have to start somewhere, but it would be lovely to also address other user personas here.

I know sections like "for testers" take time and work to develop, but perhaps we could still include them, even if almost empty, and say "Here's a few ideas and links how you can use Playground. We don't have more materials on this yet, unfortunately, but we're working hard to expand the knowledge base."

That way the documentation would at least communicate "Yes, Playground is for you. No, the guides for you aren't on another website, you can stop searching – this is all we have today."

Here's how the users were categorized for w.org/playground – it might be useful here. Another categorization might also be useful, let's just keep it in sync with w.org to make sure anyone coming from there would feel the documentation is a natural continuation of their journey.

• Developers (Plugin/Site devs, devops, Playground innovators wanting to build new experiences)
• Business (Agency owners, Managers, Teams)
• No/low-code creators (Designers, Testers, Educators)

Provide entry points for different user profiles

Yes! That sounds amazing!

Highlight/surface links to Docs from different resources related to WP Playground

Please share all your ideas related to this as they come.

I'd love all these tools (Playground block, VS Code extension, PR previewers, the upcoming documentation flow etc.) to link somewhere where the users could learn more.

w.org/playground would be a good link placeholder for starters, but as a general landing page it is disconnected from specific use-cases. Dedicated documentation pages and w.org landing pages can be much more connected.

Use the Blueprints Gallery into the docs as examples of each step

That sounds great!

I'd also write documentation for steps as regular doc pages.

Currently they're generated from code using a custom TypeScript->Markdown integration that I'd love to ditch. It requires maintenance, won't work for the PHP library once we move there, and doesn't actually solve the problem it was meant to solve – forcing the developers to always update these docstrings. We'll have to solve that one anyway, but let's do it using reliable publishing tools :-)

Guides 🆕 🔗 /wordpress-playground/guides - create new section with misc guides interesting for users (according to feedback received and questions from the community

💯 Yes please!

I meant the Docs stack: right now, it's Docusaurus on GitHub

@ironnysh I'd start with what we have, so Docusaurus. Once WordPress for Docs is ready we'll migrate the content. It's on a near-term roadmap and I expect this to happen sooner than later, but I wouldn't block content improvements on the publishing tool

---

Also, would you like to have a dedicated GitHub Milestone set up for this?

[ironnysh]

@adamziel, re Docusaurus: 💯 shouldn't block making improvements. It was more of a general interest question 😄

[ironnysh]

Perfect candidate for a guide right here: Recap Hallway Hangout: Theme Building with Playground, Create-block-theme plugin, and GitHub
@bph already did all the work adapting it! 🙌

[justintadlock]

Overall thoughts on the first draft of this outline: I don't know if the user pathways are best represented.

I also want us to think about use cases as pathways rather than defining these groups (e.g., user, themer, developer) that can overlap. For example, would be it beneficial to think in these terms?

What do you want to do with Playground?

• Try WordPress before installing it? Go here →
• Test a theme you like? Go here →
• Test a Gutenberg PR? Go here →
• Build a demo of your block? Go here →
• Build an app with Playground? Go here →

I don't know which is the best method to present this but wanted to offer an alternative method to think about.

---

Provide entry points for different user profiles
From Handbooks
Theme Handbook Create a new section called WP Playground for theme developers 🆕 🔗 /plugins/playground-theme-developers - highlighting all the WP Playground info relevant to theme developers (steps blueprints, demos...)

For clarity, do you mean To Handbooks rather than From Handbooks? Just want to make sure because there are different implications.

If we're pointing from the Playground Docs to the Theme Handbook, we'd want to create a new chapter called Playground (e.g., developer.wordpress.org/themes/playground). This would need several sub-docs that covered each of the Playground topics themers need to know about.

If we're creating a landing page from the Theme Handbook to the Playground Docs, we'd create a sub-page under the Advanced Topics chapter (e.g., developer.wordpress.org/themes/advanced-topics/playground). This would explain Playground and link to the Playground Docs.

[juanmaguitar]

Thanks for your feedback @justintadlock

I also want us to think about use cases as pathways rather than defining these groups (e.g., user, themer, developer) that can overlap. For example, would be it beneficial to think in these terms?

What do you want to do with Playground?

Try WordPress before installing it? Go here →
Test a theme you like? Go here →
Test a Gutenberg PR? Go here →
Build a demo of your block? Go here →
Build an app with Playground? Go here →

I think we can have both (use cases and some kind of groups for user personas). I see the pathways you suggest as something that should be on the landing page itself, and the specific content could be either on some of the "Guides" or under some of the other sections.

For clarity, do you mean To Handbooks rather than From Handbooks? Just want to make sure because there are different implications.

I meant "from handbooks". I think it makes sense to take playground where the theme or plugin developers "live".

If we're creating a landing page from the Theme Handbook to the Playground Docs, we'd create a sub-page under the Advanced Topics chapter (e.g., developer.wordpress.org/themes/advanced-topics/playground). This would explain Playground and link to the Playground Docs.

Yes, I was suggesting something like that. Maybe we could try to make Playground a "first class citizen" and surface it even more by creating a top level section such as developer.wordpress.org/themes/playground (or developer.wordpress.org/plugins/playground)

---

I'm actually liking the groups created at https://wordpress.org/playground/, so maybe we could go with them (instead of using user personas) in the docs, creating specific sections for:

• Build
• Test
• Launch

Also, the more I think about Playground Docs, the more I think there should be separated Docs sites for Playground Docs needs:

• One generic to introduce Playground and the landing page for all docs needs
• One for Developers (and maybe another specific for blueprints)

If we agree on this direction, this is something to be taken into account as we improve the current version.

[adamziel]

I'm actually liking the groups created at wordpress.org/playground, so maybe we could go with them (instead of using user personas) in the docs, creating specific sections for:
Build
Test
Launch

That would be ideal – we could directly connect the site and the docs and speak the same language to the same user groups 👍

Also, the more I think about Playground Docs, the more I think there should be separated Docs sites for Playground Docs needs:

• One generic to introduce Playground and the landing page for all docs needs
• One for Developers (and maybe another specific for blueprints)

I had the same thoughts – the focus and content would be vastly different in these different docs sites.

[juanmaguitar]

I've created the following PR (still in draft) #1602 to share a more tangible proposal of how a restructuration of WP Playground Docs content could look like

[adamziel]

Now that the fantastic #1602 is merged, what would you say are the next steps here @juanmaguitar?

[juanmaguitar]

Now that the fantastic #1602 is merged, what would you say are the next steps here @juanmaguitar?

I consider #1663 and #1664 the next and final steps for this issue.

[adamziel]

Thank you @juanmaguitar, that sounds spot on!

[juanmaguitar]

I consider #1663 and #1664 the next and final steps for this issue.

Closing this issue as #1663 and #1664 issues are now closed thanks to #1747, #1732 and #1750

The pending guides planned for this issue have been published today in the WP Playground Docs

• Providing content for your demo with WordPress Playground
• WordPress Playground for Theme Developers
• WordPress Playground for Plugin Developers