Playground Documentation overhaul

[adamziel]

WordPress Playground documentation contains points of information a motivated developer can put together, but it doesn't write a coherent story how to get from zero to an expert.

Let's lean into the four kinds of documentation model and separate:

• Tutorials
• How-to guides
• Explanations
• Reference

Proposed content plan

User personas

• WordPress student
• WordPress educator
• Theme / Plugin Tester
• Theme builder
• Plugin developer
• Site builder
• WordPress Core developer

Types of content for these personas

• Use Playground website to do X
  • For WordPress testers
  • For WordPress educators
  • For WordPress developers
• Use Playground API to do X
  • For Playground app developer
  • For WordPress developers
• Deep technical dives on how Playground is built
  • For Playground app developer
  • For Playground contributors

Specific content outline

• Use Playground website to do X
  • About Playground
    • What is Playground?
    • Playground features
    • Why WordPress?
    • Why Playground?
    • Playground applications
  • Tutorials
    • https://learn.wordpress.org/tutorial/how-to-start-using-wordpress-playground/
    • Using the playground for documentation and training #606
    • From Playground User Documentation #1074:
    • How to test new WordPress features?
    • How to translate WordPress?
    • How to test a plugin or a theme? (on different PHP and WordPress versions)
    • How to build a WordPress theme?
    • How to prepare for a WordPress meetup?
    • How to save my Playground site for later?
    • How to share my Playground site with the world?
    • How to collaborate on my Playground with a friend?
    • How to prepare a WordPress site for a video or live presentation?
    • How to prepare interactive materials for a workshop? (Playground block, wp-now)
  • Tools overview
    • wp-now
    • VS Code extension
    • Playground Block
    • Playground plugin
    • Live translations
    • Blueprints community space
• Use Playground API to do X
  • Explanations
    • About Playground
      • What is Playground?
      • Playground features
      • Why WordPress?
      • Why Playground?
      • Playground applications
    • Core concepts
      • Playground vs PHP.wasm
      • Playground initialization flow
        • PHP/WP versions
        • PHP extension bundles
        • Networking
      • Isomorphic WordPress
        • WordPress in JavaScript
        • Run in any environment
      • Storage, filesystems
      • Snapshots
      • Embedding Playground, CORS
    • Playground API
      • Playground Website vs JavaScript API endpoint
      • Query API
      • Blueprints API (+CORS context. Touch on the topic, link out to separate Blueprints documentation Blueprints developer documentation blueprints#2)
      • JavaScript API (+CORS context)
    • Debugging your app in Playground
      • Loggers, logger API
      • Console.logs, var_dumps
      • Message passing (post_message_to_js, postMessage bridge)
    • Playground in Node.js
      * @php-wasm/node
      * NODEFS with link to architecture
      * wp-now
    • Limitations
      • PHP extensions: CURL, XDebug
      • Raw network sockets
      • Playground on the Edge
      • Can't check if I'm running in Playground in PHP
    • Architecture (a subset useful for this context)
      • Iframes, service workers, web workers, WASM
      • Scopes (web-specific)
    • Advanced topics
      • Passing messages to / from Playground
      • Playground for native mobile apps
      • Synchronizing filesystems
      • Network handlers
      • Process handlers
  • Playground Tutorial
    • Build an app step by step – a live preview of a plugin or a theme?
    • Start with Query API
    • Involve Blueprints
    • Transition to JavaScript API
    • Deploying
  • How to?
    • Run WP-CLI?
    • Start a multisite? (Blueprints)
    • Build a PR Previewer?
    • Host your own Playground (Don't! use Blueprints and Snapshots. If you really want that, though, here's how)
    • How to build an entire WordPress plugin in Playground?
    • Build a plugin preview? (link to the tutorial)
    • Save my Playground site?
    • Programatically interact with the embedded WordPress?
      • Message passing
      • Example: translate.wp.org
    • Embed a specific site in Playground? (Blueprints, Playground plugin)
    • Clone my site in Playground? (Playground plugin)
    • Embed Playground in WordPress? (Playground block)
  • API Reference
    • Query API
    • Blueprints API
    • JavaScript API client (PHP Class, WebAPI additions)
    • IFrame postMessage protocol
• Deep technical dives on how Playground is built
  • Copy the materials from the existing documentation. Core contributors will manage and they'll improve those as they go.

Discussion

Here's some related thoughts on what might be useful:

• A tutorial – Emphasize the practical, hands-on learning approach as the primary way to get started.
• Context – Explain more about Playground. What is it built on? Show the bigger picture of WASM/WordPress. How does it fit into the ecosystem? This helps developers understand the value proposition.
• API Reference – it's not very useful at the moment. Simple PHP class structure #514 should help a lot.
• Live examples are great, let's use them a lot. Ideally, let's source them from docstrings to always keep them in sync with the code.
• Structure the learning content to answer common questions developers have after getting started, like "Why is this important?", "What are the advantages?", "How does this compare to other solutions?".
• Proactively address potential knowledge gaps like performance, compatibility etc. Call out these topics explicitly in the docs navigation so developers can easily find answers.
• Strive to minimize the need for a separate FAQ by comprehensively answering developer questions directly in the docs.

Related resources

• Examples of great docs:
  • https://gitbook-docs.frontity.org/
• Feedback and questions from real users
  • Using Playground for teaching #899
  • Questions, and thoughts... #852
  • Best way to handle a full import/export from a live site #601
  • Using the playground for documentation and training #606
• Other threads and discussions
  • https://learn.wordpress.org/tutorial/how-to-start-using-wordpress-playground/
  • https://developer.wordpress.org/plugins/wordpress-org/previews-and-blueprints/
  • https://meta.trac.wordpress.org/ticket/7487
  • Introduction/Overview of WordPress Playground developer-blog-content#198
  • WordPress Playground documentation Documentation-Issue-Tracker#1489
  • WordPress Playground documentation Documentation-Issue-Tracker#828
  • Blueprints developer documentation blueprints#2
  • Blueprint review checklist blueprints#42
  • Update the woocommerce-product-feed blueprint.json blueprints#64
  • Playground Documentation overhaul #772
  • Playground User Documentation #1074
  • A doc page to list everything you can do with Playground #1094

[adamziel]

@zzap @flexseth @dmsnell @akirk @bph @annezazu @justintadlock @ironnysh @ndiego In the issue description, I've drafted a content outline for the general Playground documentation and developer resources to kickoff a conversation here.

I'd love your input and thoughts on:

• Do the user personas sound sensible?
• Does the overall structure seem sound?
• What's missing? What's too much? What's unclear?
• How would you remodel that?
• Any other thoughts at all!

I know certain development-oriented page titles may sound opaque. That's fine. At this stage I'd like to stay at a higher level and discuss the overall approach, not specific pages. My goal is to:

1. Converge on a content structure that is the most sensible and helpful
2. Prioritize the sections that would have the most impact. My top 3 picks below - I'm interested in your take:
   1. Blueprints introduction and examples to unblock the Blueprints community space
   2. How-tos for Playground API to get devs on board.
   3. How-tos for Playground website to map out the no-code possibilities.

LMK if the docs repo would be a better place for this discussion.

[flexseth]

@adamziel - if you can do your best to not edit the bullet points above, I'm cross-referencing them and consolidating all of the information into one place.

Later today that should be available for preview, most likely it would be a comment on this thread with a copy/paste of what is above, and then links to the relevant information. I can then update the bullet points on that same comment with the links to relevant information.

I've been using the "Link to Highlight" feature in Chrome to copy text and create a link, but in a few cases it looks like there are GitHub issues for the bullet points.

Give me a few and I'll post a list that will be a working list based on the bullet points!

[annezazu]

User personas

For user personas, I'd make the testing one more general as that could cover releases (gutenberg and core).

Does the overall structure seem sound?

Yes! I think you cover everything that would be needed to launch.

What's missing? What's too much? What's unclear?

I mainly want to underscore this later point: "Live examples are great, let's use them a lot. Ideally, let's source them from docstrings to always keep them in sync with the code.". I think leading with examples is key, especially to pull in folks who aren't as technical.

The main thing missing to me is where to go to share feedback about playground - bugs or requests.

[flexseth]

The main thing missing to me is where to go to share feedback about playground - bugs or requests.

@annezazu spot on! Added to the top of marked up notes.

Progress Report

Marked up most everything from every conversation I've found on GitHub so far. This does not include the documentation that already exists.

Here's my proposal for improving the documentation and a roadmap for the Docs v2 and really getting the word out about the Playground.

The idea is to create a simple, docs-looking theme that uses WordPress's baseline functionality via a taxonomy and organizational structure that just. makes. sense.

Annnd here's the cool part/proposal: I want to build this out using the Playground.

The idea is to build a prototype, have it available as a Blueprint, and then folks can open an issue based on a page, post, snippet, or idealogical pattern to work on.

Code Name: School Yard

The foundation will be laid out with as much content as I can wrangle from the existing docs, with a roadmap for content that isn't quite production ready yet but has been discussed. Whoever wants to work on the project can spin up the site, work on what they want, rename and re-submit their prototype for the world to see their content ideas. Ideally with everyone taking on different points of interest.

At first it will be a little dry looking, but maybe we can get the design team involved for some iconography and subtle hints as the project comes together iteratively.

Site Structure

• Pages: General Information
• Posts: Rolling content: Project and functionality updates, code from the Blueprint Community Space, and content relevant to new Core and Gutenberg features
• Blueprints: Theme and Plugin demos, show & tell of sorts, rolling content
• Snippets: A part of a Blueprint (via PHP Doc Blocks)
• Step-by-Step / How-To Guides: Tutorials to create what you see above
• Advanced Administration - Configurations, architecture, under the hood

User Roles

• New Users: Test WordPress out, see the admin, demo a theme, demo a full site
• End-User: General Info about the Playground
• Demo: Some overlap here, but the idea is to show a Proof of Concept
• Trainers/Organizers: Easily spin up sites to work on, show features at Meetups/etc
• Contributor: Interested in being involved with Blueprint
• Developer: Theme and Plugin authors

Maybe the coolest part 😎

When building this out it will create the content along the way.

While marking this up all I'm seeing is search keywords, taxonomy, and it looks like a lot of the content is already there. Once it's all done it can be hosted as a site on the WP.org multi-site network, with a footer that reads

"Built with a Blueprint"

[ndiego]

Added to the top of marked up notes.

@flexseth are you able to share these notes?

Annnd here's the cool part/proposal: I want to build this out using the Playground.

Cool idea, but I believe the plan is to keep the current infrastructure (https://wordpress.github.io/wordpress-playground/) but overhaul the content. Is this correct, @adamziel? Updating the content is going to be a substantial undertaking, so my recommendation would be to simplify the rest of the project by continuing to use Docusaurus. The content can always be moved somewhere else in the future.

[flexseth]

@flexseth are you able to share these notes?

I printed out all of the issues mentioned in this thread and spidered out to the links from there, printing them also. Then went through and marked them up in pen, grouping ideas together by taxonomy. Crossing out duplicates/etc. It's how I look at larger projects for discovery.

At first I was doing everything in Notion but as I went along it seemed like the content was very WordPress-y.. I was thinking WordPress for SEO purposes mainly. In another thread @adamziel mentioned WP.org (WordPress powered) was an option, that's why I was leaning that way.

If Markdown or another platform is preferred, it could be exported. But a lot of the features like subscribing for email updates and such wouldn't be there.

Let's say you wanted to build a Blueprint Generator, something that you could do with WordPress if the content was there. Share a blueprint etc... guess I was looking at it more like a platform than just a set of documentation.

For me the idea really boiled down to "Doing things the WordPress way." 😀

Completely open to suggestions. What I was going to do was import the posts from a spreadsheet, with the taxonomies, and see what type of Playground magic could happen.

I do have concerns from a SEO standpoint about putting a bunch of content in GitHub, when it could be on WordPress, though.

Gonna double down on that last point... if you're trying to bring new people into the WordPress Community, and can quickly deliver them a working product, I feel like it's very important for that experience to be as search engine friendly as possible.

As to the actual infrastructure: It would be another site in the multi-site network.

[zzap]

I just want to add here a deeper explanation of the four type documentation system @adamziel referenced at the beginning: https://documentation.divio.com/introduction.html

[adamziel]

Cool idea, but I believe the plan is to keep the current infrastructure (https://wordpress.github.io/wordpress-playground/) but overhaul the content. Is this correct, @adamziel? Updating the content is going to be a substantial undertaking, so my recommendation would be to simplify the rest of the project by continuing to use Docusaurus. The content can always be moved somewhere else in the future.

I love the idea of using Playground for writing the docs:

• It's much easier – it's just a click, there are no build tools, local setups etc.
• It's extra testing for Playground.
• Embedding live examples would be easy via the Playground Gutenberg block.
• It could generalize to WordPress documentation later on.

My one concern is the setup cost – would it take hours or weeks to set it up? If hours, then let's just do it and explore this. We can always migrate the content to markdown if it doesn't pan out. If weeks, let's put it on hold, start a tracking issue, and focus on preparing immediate resources for the Yoast Contributor day, WCEU, Blueprints community space etc.

@flexseth would you please start a new issue to track and explore this specific idea?

[adamziel]

@ellatrix would you share your $wpdb <-> HTML files integration? It could make the entire idea "just work" even with local files. Edit – it's here:

• https://github.com/ellatrix/blocknotes/blob/main/src/js/plugin.php
• https://github.com/ellatrix/blocknotes/blob/main/src/js/insert.php
• https://github.com/ellatrix/blocknotes/blob/main/src/js/actions.php

It treats local files as WordPress posts and persists any changes made in the editor back on the disk.

The easiest way to set it up would be something like this:

1. Create a Blueprint that puts the docs pages in the Playground filesystem (writeFile).
2. Redirect to the relevant edit post page, or create a bunch of new pages.
3. Edit the docs pages, do the needed work.
4. Once you're finished, there's a "download" button in wp-admin that zips and downloads those doc pages so you can submit a PR to the docs repo.

Even better if all the changes were also saved in localStorage or OPFS in case Playground crashes

This isn't super convenient with all the downloads, so here's a few improvement ideas for later:

1. Connect a local directory using Playground's OPFS integration, directly edit local files
2. Integrate with GitHub, enable submitting PRs directly from the editor – similar to what "Export to GitHub" already does. Actually, I wonder if it would just work as it is?

[adamziel]

Also capturing the notes from a call with @flexseth and @zzap

Immediate docs roadmap

• Get more contributors, teach them how it works, make sure they can use it.
• Developer docs – priority – making sure they can use it, break it, request features
• Onboarding devs: to project, to team, to idea itself. Then they start having their own ideas. That’s 50% job done.
• Blueprints are important, most integrations will only need them
• Advanced use-cases – let’s wait for more questions
• Finding the widest use-cases
• Major roadblocks – fixing or describing them. E.g. VS Code Blueprints.json, extra PHP extensions
• Templates and pages for things that don’t work – what blocks people.
• User documentation – for educators

Yoast contributor day prepwork

• Answer: “how to get started? I only know basic WP structure”
• Tech – “Start developing a WP plugin in Playground – how do I do that?”
• Where do I create this or that file? Put it? Run it? Blueprint.json expecially
• Team – “How to guide?”
• Very specific steps – no details – Milana can ask a few devs for feedback on: What’s unclear? What didn’t work? What questions did they have?
• Specific scenarios to follow.

[flexseth]

Here are my notes following our meeting. They most likely correlate a bit to what @adamziel has above:

---

Meeting Notes: Overview

User personas - start with documentation for most popular use cases for developers

• High return on time investment, discovers limitations and bugs, showcases features
• Helps to establish roadmap / plan out ideas for features
• Stabilizes documentation and starts building out the framework for blueprint community

Product Roadmap

Provide more transparency on the current limitations with Blueprint

• What does not work right now (link to issues)
• System requirements
• Suggest a feature or improve this documentation
• Start with developer docs and blueprint community
  • Build out documentation pages using blueprints > Gutenberg > export WXR > GitHub
• Improve labeling system on Playground GitHub repo so users can better search discussions

Onboarding

Developers: Get started using the Playground

• Clear workflow on how to report bugs
• Clear workflow on how to request a feature
• Frequently Asked Questions
• Limitations
• Start with Developer persona as a use case
  • Using WordPress Playground locally - possibly include CORs fix as mandatory
  • Addressing common local development pitfalls, reduce workarounds

Using the WordPress Playground for local dev

• Addressing common issues with local development
  • Add in CORs for importing blueprints
  • Using wp-cli with Playground
  • Understanding the file system
  • etc - pull from notes

Popular existing developer use cases

WordPress.org Plugin Preview Builder

• Install Blueprint
• Creates blueprint.json file
• Integrates with SVN
• Submit to WP.org
• all in one blueprint

Create Block - Make a new, custom WordPress block

PR Previewer - compare a PR for Gutenberg - does this fix the issue?

Create a plugin

• Runs steps necessary, scaffolds plugin files based on user input (CLI/GUI)
• Blueprint preview button - ensure works on WP.org

Opportunities

Improve documentation - Create a documentation improvement request via a blueprint

• Developer Docs
• Theme Documentation
• Improve Make
  • Report an issue
  • Improve a page
• Modify a handbook
  • Workflows need to be ironed out on a per-handbook basis
  • Start with
    • Developer documentation
    • Improve Playground or Blueprint docs
    • General issue on Documentation Issue Tracker - blueprint for creating
• Add sample code: Add a code sample to block-development-examples
  • Playground pulls down everything needed to build the environment, builds it
• Create a Plugin - Boilerplate Blueprint to create a plugin
  • Interactive CLI or GUI for creating a new plugin with modern workflow
    • building with wp-scripts
    • without @wordpress/scripts
  • Plugin Submission Guidelines Blueprint
  • Lints & reports errors
• Demo - Showcase something you are working on, Proofs of Concepts
  • Test out a pattern on a theme
  • etc - come up with more common demo ideas
• Testing
  • Run your plugin past the review team
  • Test your plugin for security vulnerabilities
  • Test for missing dependencies
  • Run your theme past the theme check
  • Testing a Gutenberg PR
  • Using Playwright in Playground

[flexseth]

Updated taxonomy suggestions for this GitHub repository

• New labels for WordPress Playground GitHub #1160

[flexseth]

• It could generalize to WordPress documentation later on.

Handbooks.

Simply put: Blueprints could be used to build out a link to updating the various handbooks.

Workflow

User wants to contribute to a handbook. Whether that is updating a single word, or adding a code sample, blueprints can be used to create a simple user interface to update documentation.

• Link from content to the blueprint for contributing to this handbook
• User builds the Playground with blueprint
• Playground includes instructions for updating this piece of content
• Enforces correct contribution flow, style guidelines, code standards, etc
• User updates documentation via the Block Editor
• Export post for review, attaching the blueprint to the issue
• Handbook update goes through review process (also a blueprint workflow)
• Once approved, the updated markup for the Block Editor can be imported to relevant WP.org handbook to replace existing copy or create a new page in the handbook

Lowers the barrier of entry of having to use GitHub to contribute.

Now anyone can easily contribute to fix a misspelling, add better paragraph spacing, or add a code example

[flexseth]

Introduced some project ideas on the documentation board

• https://github.com/orgs/WordPress/projects/183/views/1
  (They are set to draft now, not sure I can publish there with existing permissions)

[flexseth]

@adamziel - I don't want to be the one to mention this, but Docusaurus is 100% not search engine friendly.

Proof of concept

Search for "activateTheme step playground"

Going to label this as a bug... ...

A little bit more info

Search engine optimization is something I have done for clients and something I've been really interested in for a long time. Actually really good at it....

As WordPress grows and continues to gain market share, I believe at my core it is imperative that all of the documentation should be search engine ready.

[adamziel]

@flexseth aha, good find! I'd like to migrate from Docusaurus to WordPress sites once Playground-based workflow is mature enough.

[adamziel]

Let's close this one in favor of #1518