search

WordPress / wordpress-playground

Run WordPress in the browser via WebAssembly PHP
https://w.org/playground/
GNU General Public License v2.0
1.58k stars 222 forks source link

Improving the learning journey of WordPress Playground in the Docs #1518

Open juanmaguitar opened 3 weeks ago

juanmaguitar commented 3 weeks ago

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.

ironnysh commented 3 weeks ago

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

A few questions:

juanmaguitar commented 3 weeks ago

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:

ironnysh commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

Got it 👍

adamziel commented 2 weeks ago

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.

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 commented 1 week ago

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

ironnysh commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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:

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

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

adamziel commented 1 week ago

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.