@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.

@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!

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.

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"

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

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

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?

@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?

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.

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

Updated taxonomy suggestions for this GitHub repository

• New labels for WordPress Playground GitHub  #1160

• 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

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)

@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.

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