Tracking: Redesign Documentation

[adamziel]

Description

With so many API changes recently merged, the current documentation is largely outdated. Let's revamp it with specific use-cases in mind. I'd like to directly answer questions like:

• Getting started
  • Sales pitch
    • WordPress Playground allows you to...
    • A few examples what people built
    • A blurb of what you can build
    • 1 minute code example with jsfiddle (or so) link
  • Table of contents of the entire doc site
  • Contributing (summary + link to a separate section)
• How do I use WordPress Playground to... (link to specific pages that bring the tiny bits of knowledge together)
  • ...start a site with a specific plugins, themes, starter content, and a WP or PHP version? (Document "How to install a plugin" #198, [Import/export] Support WXR, WXZ, and full-site import and export #209)
  • ...showcase my plugin or theme? (install a plugin, import starter content, set WP and PHP version)
  • ...control the embedded website?
  • ...provide interactive code snippets?
  • ...preview pull requests from my repo?
  • ...setup a development environment without installing Apache or MySQL? (wp-now, VScode extension)
  • ...test my plugin on different WordPress and PHP versions?
  • ...use my own Progress Bar?
  • ...(what else?)
• Tech details: How to embed and control WordPress Playground in my web app?
  • A brief glimpse of all the different methods. Direct links. Enourage to stop and learn about the mental model first.
  • Mental model: Endpoints, iframes, inter-iframe communication
    • Choose your endpoint: index.html vs remote.html
    • Inter-iframe communication Comlink.js inwards, postMessage relay outwards.
  • APIs (each with a discoverable list of methods and usage examples; ideally autogenerated from code so that it doesn't have to be kept in sync manually)
    • Easy: Query String API
    • Easy+ Blueprints
    • Medium: PlaygroundClient
• How does WordPress Playground work under the hood?
  • Reuse these existing materials to write this section:
    • High-level overview at web.dev
    • Existing doc pages: (PHP in JS, PHP in the browser, WP in the browser
    • Initial wp.org announcement
  • SQLite vs MySQL, Status update on the SQLite project, SQLite support via a MySQL parser
  • Bundling WordPress on the web
• How to develop PHP.wasm?
  • Mental models explained:
    • PHP->WASM Build pipeline (Dockerfile, Emscripten, SIDE_MODULES, Emscripten extensions, Filesystems, custom C patches in Playground)
    • php_wasm SAPI
    • Async calls via Asyncify, [JSPI]
    • Networking proxy and its technical limitations on the web vs in CLI(Ship the JSPI kitchen-sink build to Chrome users #134) possible in the future
  • Actual how to questions. How to:
    • Build with a new PHP extension
• Contributing
  • You don't need to know wasm. Wasm stuff make for 1% of this repo (I just made up this figure lol).
  • How to get started – "good first issues," JavaScript issues etc
  • GPL Licensing – boring stuff but important to keep in mind
  • How to...
    • Add a new package to the repo? (use NX generators, the most useful ones are...)
    • Set up a fast npm run dev command? (don't use rollup, reuse existing Vite configs)
    • Release a package for both web and Node.js? (build both .cjs and .esm, add a test:esmcjs executor to your package)
  • Overall guidelines
    • New APIs
      • Don't build new APIs unless many people ask for them
      • Don't make new APIs stable on day one, be prepared to scrape them and redo many times over
  • For core committers
    • Releasing npm packages (current vs next, keep the official remote.html working)

[adamziel]

cc @eliot-akira @akirk @johnhooks @michalczaplinski @sejas @dmsnell – I'd love to include any information you see fit in the above documentation outline. For inspiration: anything that made you go "hmmm" or "wtf?!" or "wait, how do I..." while you've been working with WordPress Playground is likely a good candidate.

[johnhooks]

That looks like a very thorough list! I for one would love to learn about the internals and concepts. I'm glad you are keeping that in mind, it would be easy to gloss over and just document the public APIs.

From the perspective of someone wanting to use this to showcase a plugin or theme:

• Fully document all the available the blueprint options and steps. The API for these is so thoughtful and elegant, I imagine blueprints will be a very popular way to configure a custom playground.

  • These might need to be documented by hand.

  • For popular use, I would assume it shouldn't have any generic type signtures in the general explanations of their use, the generated API docs can provide that amount of detail.

  • It would be really nice to have direct links between the simplified and complex documentation.

  • In my opinion, having all the available steps listed on the same page, with a table of contents, would make it fast to search and use as a reference while writing a blueprint.

• Same type of documentation for the URL API of the index.html

• In the current documentation, the concept between index.html and remote.html is hard to make sense of, especially if all your wanting to do is quickly get started. It would be nice if:

  • They had more descriptive names. Not the literal files, but the concepts, and the file names become just details about the concepts, rather than the other way around.

  • The current page explaining them feels dense, index-html-vs-remote-html. As simple as it sounds, more line height would give the concepts a bit more visual space between each other.

  • The top section of the page should be a large prioritize bullet point lists of use cases for each with directly links to how to do it.

  • The heavy technical details can be lower down the page.

[adamziel]

This is awesome, thank you @johnhooks!

They had more descriptive names. Not the literal files, but the concepts, and the file names become just details about the concepts, rather than the other way around.

I agree about the concepts part. Also, now that I'm thinking about, remote.html could actually be called api-endpoint.html, that should help, too.

[adamziel]

Let's also document debugging Asyncify issues

[jomarieminney]

• I think in the getting started section, a bit of a clarification on what the user interface aspect of playground can/can't do - i.e. limitations (you gave an excellent summary of these in Slack somewhere but I've already lost it). For example, the playground is already linked to in multiple locations in learning content, and users who come across it might not be full stack developers but rather (for example) learning how to create a theme using FSE. This is literally the case in which I discovered it and went down the rabbit hole!
  • e.g. you can't access the repo inside a demo (but you can run demo with plugins/specific theme installed, using parameters)
  • The demo is a great place to test out how a block works, without having to spin up a new site or log in and test on a live site.
  • When you refresh the page, you'll lose anything you did (unless you export it)
  • How to export it!

[adamziel]

This is such a fantastic feedback @jomarieminney! +1 on everything you said. It would be super cool if the plugins/themes directory inside wp-admin told you "oops, this doesn't work here, but here's how you can install plugins instead:".

[sagargurnani99]

I believe, in the "Getting started" section; it would be helpful to include a brief overview of what WordPress Playground is and its main features before diving into the sales pitch. Where and why to use it.

[adamziel]

Sounds lovely @sagargurnani99! Would you be interested in drafting it up?

[sagargurnani99]

Of course @adamziel.

[adamziel]

The new documentation site answers many of the questions discussed in this issue, and I created a number of follow-up issues to track anything that's not yet covered:

https://github.com/WordPress/wordpress-playground/issues?q=label%3ADocumentation+is%3Aissue

If anything in that doc is unclear, confusing, missing, or could be improved in any other way – you are the most welcome to start a new issue or a Pull Request to improve it!

cc @johnhooks – I hope the Blueprints doc is clearer now that it lists all the steps. The specific descriptions could be better for sure, but is the overall structure what you hoped for?

[johnhooks]

@adamziel looks awesome, I will give it a through read through and I will make sure to file an issue if I run into anything.