search

WordPress / wordpress-playground

Run WordPress in the browser via WebAssembly PHP
https://w.org/playground/
GNU General Public License v2.0
1.62k stars 249 forks source link

Playground Documentation overhaul #772

Closed adamziel closed 2 months ago

adamziel commented 10 months ago

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:

Proposed content plan

User personas

Types of content for these personas

Specific content outline

Discussion

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

Related resources

adamziel commented 6 months ago

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

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 commented 6 months ago

@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 commented 6 months ago

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 commented 6 months ago

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

User Roles

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 commented 6 months ago

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 commented 6 months ago

@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 commented 6 months ago

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 commented 6 months ago

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:

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 commented 6 months ago

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

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 commented 6 months ago

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

Immediate docs roadmap

Yoast contributor day prepwork

flexseth commented 6 months ago

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

Product Roadmap

Provide more transparency on the current limitations with Blueprint

Onboarding

Developers: Get started using the Playground

Using the WordPress Playground for local dev

Popular existing developer use cases

WordPress.org Plugin Preview Builder

Create Block - Make a new, custom WordPress block

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

Create a plugin

Opportunities

Improve documentation - Create a documentation improvement request via a blueprint

flexseth commented 6 months ago

Updated taxonomy suggestions for this GitHub repository

flexseth commented 6 months ago
  • 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.

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 commented 6 months ago

Introduced some project ideas on the documentation board

flexseth commented 5 months ago

@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 commented 5 months ago

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

adamziel commented 2 months ago

Let's close this one in favor of https://github.com/WordPress/wordpress-playground/issues/1518