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 https://github.com/adamziel/blueprints/issues/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
  • https://github.com/adamziel/blueprints/issues/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