Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
9 tasks
juanmaguitar opened this issue Jun 17, 2024 · 16 comments
Closed
9 tasks
Assignees
Labels
[Type] Documentation Improvements or additions to documentation [Type] Enhancement New feature or request [Type] Mindmap Node [Type] Project

Comments

@juanmaguitar
Copy link
Collaborator

juanmaguitar commented Jun 17, 2024

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
    • 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

  • 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
Copy link
Collaborator

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
Copy link
Collaborator Author

juanmaguitar commented Jun 18, 2024

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
Copy link
Collaborator

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
Copy link
Collaborator Author

juanmaguitar commented Jun 18, 2024

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
Copy link
Collaborator

Got it 👍

@adamziel adamziel added [Type] Documentation Improvements or additions to documentation [Type] Enhancement New feature or request labels Jun 24, 2024
@adamziel
Copy link
Collaborator

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
Copy link
Collaborator

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

@ironnysh
Copy link
Collaborator

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
Copy link
Collaborator

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
Copy link
Collaborator Author

juanmaguitar commented Jun 28, 2024

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
Copy link
Collaborator

adamziel commented Jul 1, 2024

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
Copy link
Collaborator Author

juanmaguitar commented Jul 11, 2024

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

brandonpayton pushed a commit that referenced this issue Aug 19, 2024
## Motivation for the change, related issues

This PR is related to the issue
#1518

Its goal to provide a better structure for WordPress Playground Docs and
a better learning journey for those navigating these docs

[<img width="1677" alt="Screenshot 2024-08-05 at 13 11 52"
src="https://github.com/user-attachments/assets/22b03afd-921a-4584-843d-0b452302496f">
](https://youtu.be/gzrW4Pht1Fc)
[See video with overhaul proposal](https://youtu.be/gzrW4Pht1Fc) 

<details>
<summary>See Video of initial version of this PR</summary>

https://github.com/WordPress/wordpress-playground/assets/422576/afdda902-e50c-4d72-b263-5a11323d1282
</details>

## Implementation details

This PR creates three different subsites to organize three big types of
docs related to WP Playground:
- **Main**: Introduction to WP Playground, First steps, and more
End-User oriented
- **Blueprints**: A specific section for this topic that is in the
middle ground between non-technical and technical users
- **Developers**: All WP playground-related info relevant for developers
with a high-level techie language

For that, three dedicated sidebars (for each one of these subsites) have
been created. All markdown files have been reorganized across three
folders and links have been updated accordingly

## Testing Instructions (or ideally a Blueprint)

- checkout this branch
- from the root of the project
  - run `npm run build:docs`
  - run `npm run dev:docs`
  
## To-Do
- [x] Add Filesystem and DB debug info as per
#1533
-
#1533 (comment)
- [x] #1529 Take
these SEO suggestions into account for final PR - no clear actions for
the docs at the moment - [awaiting for more
feedback](#1529 (comment))
- [ ] ~The breadcrumb on https://wordpress.org/playground/ reads
“Playground”, can we please make that “WordPress playground”?~
- [ ] ~Can we change the sentence “The platform that lets you run
WordPress instantly on any device without a host.” to “WordPress
Playground is the platform that lets you run WordPress instantly on any
device without a host.”~
- [ ] ~Change the sentence “A single <iframe> tag is all it takes to
integrate Playground with your application.” to “A single <iframe> tag
is all it takes to integrate the WordPress Playground with your
application.”~
- [ ] ~A small social improvement - We should really give the WP
Playground “homepage” an og:image~

---------

Co-authored-by: Adam Zieliński <[email protected]>
@adamziel
Copy link
Collaborator

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

@juanmaguitar
Copy link
Collaborator Author

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
Copy link
Collaborator

Thank you @juanmaguitar, that sounds spot on!

@juanmaguitar
Copy link
Collaborator Author

juanmaguitar commented Sep 12, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Type] Documentation Improvements or additions to documentation [Type] Enhancement New feature or request [Type] Mindmap Node [Type] Project
Projects
Archived in project
Development

No branches or pull requests

4 participants