documentation structure overhaul #1602

juanmaguitar · 2024-07-11T16:01:19Z

Motivation for the change, related issues

This PR is related to the issue #1518

Its goal to provide a better structure for WordPress Playground Docs and a better learning journey for those navigating these docs

See video with overhaul proposal

See Video of initial version of this PR

https://github.com/WordPress/wordpress-playground/assets/422576/afdda902-e50c-4d72-b263-5a11323d1282

Implementation details

This PR creates three different subsites to organize three big types of docs related to WP Playground:

Main: Introduction to WP Playground, First steps, and more End-User oriented
Blueprints: A specific section for this topic that is in the middle ground between non-technical and technical users
Developers: All WP playground-related info relevant for developers with a high-level techie language

For that, three dedicated sidebars (for each one of these subsites) have been created. All markdown files have been reorganized across three folders and links have been updated accordingly

Testing Instructions (or ideally a Blueprint)

checkout this branch
from the root of the project
- run npm run build:docs
- run npm run dev:docs

To-Do

Add Filesystem and DB debug info as per Filesystem explorer #1533
- Filesystem explorer #1533 (comment)
WP.org site feedback: SEO improvement suggestions #1529 Take these SEO suggestions into account for final PR - no clear actions for the docs at the moment - awaiting for more feedback
- ~~The breadcrumb on https://wordpress.org/playground/ reads “Playground”, can we please make that “WordPress playground”?~~
- Can we change the sentence “The platform that lets you run WordPress instantly on any device without a host.” to “WordPress Playground is the platform that lets you run WordPress instantly on any device without a host.”
- Change the sentence “A single <iframe> tag is all it takes to integrate Playground with your application.” to “A single <iframe> tag is all it takes to integrate the WordPress Playground with your application.”
- ~~A small social improvement - We should really give the WP Playground “homepage” an og:image~~

juanmaguitar · 2024-07-11T16:10:19Z

@adamziel, this is a first look of the work to reorganize the documentation. What do you think?

There's some more work to do, but the pending work will follow this content organization.
Some of the next things I'd like to tackle are:

Better introductions on some parts
Some more restructuring on each sub-site
Provide content to the Build, Test and Launch sections
Add a guidessection with at least one guide

juanmaguitar · 2024-07-11T16:59:36Z

As per @bph feedback, I have added a more prominent highlight to the "active" site.

Screen.Recording.2024-07-11.at.17.52.10.mov

justintadlock · 2024-07-11T17:42:54Z

Overall, I really like how this is structured and believe it's a good way to organize the different learning pathways for the different user groups.

adamziel · 2024-07-15T21:10:54Z

This is incredible @juanmaguitar, thank you ❤️ The structural changes already made for such huge clarity improvement I almost can't believe it. Please keep doing what you're doing 💯

adamziel · 2024-07-29T14:15:50Z

It would be highly useful to visibly the Blueprint gallery from the Blueprints section

adamziel · 2024-07-29T14:16:18Z

Also, any updates here @juanmaguitar?

richtabor · 2024-07-29T14:16:40Z

Just dropping a comment here, not on the design/layout but more on discoverability:

Dev experience wise, it seems we can do better on pushing use cases better, rather than just the information. Like a case study (short, concise) for a theme author setting up a demo, what works best, linking to all the API docs for steps, gallery entires for the theme category, etc.

O one for demoing plugins, one for pull request previews for theme authors, for plugin authors, etc.

Just quick idea as I was exploring adding a blueprint to one of my themes.. Like, I'm not sure if I should include the blueprint .json file in the theme download.

juanmaguitar · 2024-07-29T17:13:42Z

Also, any updates here

@adamziel I've uploaded some more progress in the docs overhaul with new content for the intro page among other updates.

wp-playground-july-29.mov

juanmaguitar · 2024-07-30T08:33:53Z

It would be highly useful to visibly the Blueprint gallery from the Blueprints section

@adamziel I agree! In the current work I'm doing, the Blueprints Gallery are highlighted first thing in the Blueprint space

I'll think of more ways to give the Blueprints Gallery more visibility.

@richtabor is there any other section in the docs that would've felt natural for you to find a reference to the Blueprints Gallery

adamziel · 2024-07-31T11:48:12Z

Yay, lovely work here!

adamziel · 2024-07-31T13:04:44Z

Surfacing this issue as it's relevant here #1529

richtabor · 2024-07-31T14:10:58Z

@richtabor is there any other section in the docs that would've felt natural for you to find a reference to the Blueprints Gallery

I think next, more together case studies: WordPress Playground for Theme Designers, WordPress Playground for Plugin Developers, etc.

richtabor · 2024-07-31T14:11:59Z

Instead of "a variety of ways" how about something about "real-world code examples"?

juanmaguitar · 2024-07-31T15:38:28Z

I think next, more together case studies: WordPress Playground for Theme Designers, WordPress Playground for Plugin Developers, etc.

For this overhaul I was planning to include in the new guides section two initial guides: one for theme developers and another one for plugin developers

@richtabor Which key ideas would you like to see reflected in these guides?

I opened #1663 and #1664 to gather feedback around these guides

…anmaguitar/wordpress-playground into docs/documentation-overhaul

packages/docs/site/docs/main/about/launch.md

packages/docs/site/docs/main/intro.md

packages/docs/site/docs/main/about/build.md

adamziel · 2024-08-09T13:40:27Z

1

@@ -0,0 +1,6 @@
+Merge branch 'docs/documentation-overhaul' of github.com:wordpress-juanmaguitar/wordpress-playground into docs/documentation-overhaul


We can remove this file

adamziel · 2024-08-09T13:41:26Z

It looks great at the first glance. I'll keep reading and reviewing next week. Let me CC @richtabor @ironnysh @bph @justintadlock for their feedback.

Co-authored-by: Adam Zieliński <[email protected]>

justintadlock · 2024-08-09T14:52:24Z

Overall, I'm happy with the direction of this as the foundation we need for the docs. I'd go ahead and push forward with it, and we can iterate on it afterward.

adamziel

I'm impressed @juanmaguitar. There is so much goodness here. It's a profound step towards making Playground useful and accessible to everyone. Thank you so, so much 🎉

adamziel · 2024-08-18T22:49:49Z

Github won't let me merge until the conflicts are resolved. Would you please rebase or merge @juanmaguitar? I'm afk this week but @brandonpayton will help with merging.

adamziel · 2024-08-18T22:50:23Z

packages/docs/site/docs/blueprints/07-json-api-and-function-api.md

+
+You can use Blueprints both with the web and the node.js versions of WordPress Playground.
+
+:::info Blueprints version 2


adamziel · 2024-08-18T22:50:34Z

packages/docs/site/docs/blueprints/08-examples.md

@@ -7,6 +7,10 @@ import BlueprintExample from '@site/src/components/Blueprints/BlueprintExample.m

 # Blueprints Examples

+:::tip
+Check the [Blueprints Gallery](https://github.com/WordPress/blueprints/blob/trunk/GALLERY.md) to explore real-world code examples of using WordPress Playground to launch a WordPress site with a variety of setups.


adamziel · 2024-08-18T22:50:59Z

packages/docs/site/docs/blueprints/09-troubleshoot-and-debug-blueprints.md

@@ -22,20 +21,51 @@ The editor is under development and the embedded Playground sometimes fails to l

 :::

+## Check for the Filesystem and Database


I'm really happy to have this section in the docs. Thank you!

adamziel · 2024-08-18T22:51:43Z

packages/docs/site/docs/blueprints/09-troubleshoot-and-debug-blueprints.md


 If you haven't yet, enable the Develop menu: go to **Safari > Settings... > Advanced** and check **Show features for web developers**.

 :::

 The developer tools window allows you to inspect network requests, view console logs, debug JavaScript, and examine the DOM and CSS styles applied to your webpage. This is crucial for diagnosing and fixing issues with Blueprints.

+## Log your own error messages
+
+You can `error_log` your own error messages through [`runPHP` step](./steps#RunPHPStep) (see [blueprint example](https://github.com/wordpress/blueprints/blob/trunk/blueprints/reset-data-and-import-content/blueprint.json) and [live demo](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/reset-data-and-import-content/blueprint.json)) and check them from the ["View Logs" option](../main/web-instance.md#playground-options-menu) or from the browser's console.


Yay! This is another lovely and useful nugget

adamziel · 2024-08-18T22:52:16Z

packages/docs/site/docs/blueprints/intro.md

+-   [**Developers**](/wordpress-playground/developers) – WordPress Playground was created as a programmable tool. Discover all the things you can do with it from your code in the Developers docs hub.
+-   [**API Reference**](/wordpress-playground/api) – All the APIs exposed by WordPress Playground
+
+## Navigating the Blueprints documentation hub


juanmaguitar · 2024-08-19T08:18:10Z

Github won't let me merge until the conflicts are resolved. Would you please rebase or merge @juanmaguitar? I'm afk this week but @brandonpayton will help with merging.

@brandonpayton I have solved the conflicts. The PR is ready to be merged but I cannot merge it.
Could you do the merge? Thanks!

brandonpayton · 2024-08-19T12:05:22Z

@juanmaguitar Sure thing. Done!

documentation structure overhaul

b91b435

juanmaguitar mentioned this pull request Jul 11, 2024

Improving the learning journey of WordPress Playground in the Docs #1518

Closed

9 tasks

add background to highlighted subsute

3606564

adamziel assigned juanmaguitar Jul 12, 2024

adamziel added the Needs Author's Reply label Jul 16, 2024

adamziel mentioned this pull request Jul 16, 2024

WP.org site feedback: SEO improvement suggestions #1529

Closed

Merge branch 'trunk' into docs/documentation-overhaul

28a9c41

adamziel removed the Needs Author's Reply label Jul 29, 2024

juanmaguitar added 2 commits July 29, 2024 18:06

Intro to WP Playground Docs

7316772

Merge branch 'trunk' into docs/documentation-overhaul

3058130

checked grammar

704c935

juanmaguitar added 5 commits July 30, 2024 10:13

Fixed links

e746d88

better spaces navigation

b98c16a

Manual sidebar configuation

58397d3

Updated structure

10fa3db

Main pages content

308431d

juanmaguitar added 3 commits August 9, 2024 11:53

Merge branch 'trunk' into docs/documentation-overhaul

01047e0

Merge branch 'docs/documentation-overhaul' of github.com:wordpress-ju…

62d6331

…anmaguitar/wordpress-playground into docs/documentation-overhaul

Clearer intro sentences for docs hubs

3f13077

juanmaguitar requested a review from a team as a code owner August 9, 2024 12:02

adamziel reviewed Aug 9, 2024

View reviewed changes

packages/docs/site/docs/main/about/launch.md Outdated Show resolved Hide resolved

adamziel reviewed Aug 9, 2024

View reviewed changes

packages/docs/site/docs/main/intro.md Outdated Show resolved Hide resolved

adamziel reviewed Aug 9, 2024

View reviewed changes

packages/docs/site/docs/main/about/build.md Outdated Show resolved Hide resolved

adamziel reviewed Aug 9, 2024

View reviewed changes

juanmaguitar and others added 4 commits August 9, 2024 15:21

Update packages/docs/site/docs/main/about/launch.md

0eb7f97

Co-authored-by: Adam Zieliński <[email protected]>

Update packages/docs/site/docs/main/about/build.md

171e521

Co-authored-by: Adam Zieliński <[email protected]>

Update packages/docs/site/docs/main/intro.md

9641526

Co-authored-by: Adam Zieliński <[email protected]>

removed unnecesary file

8dc9bcf

juanmaguitar requested a review from adamziel August 9, 2024 14:25

juanmaguitar added 3 commits August 9, 2024 16:04

redirections info on resources page

ff3d469

connect playground instance to local directory

2c9b218

offline mode and PWA support

d45c541

adamziel approved these changes Aug 18, 2024

View reviewed changes

Merge branch 'trunk' into docs/documentation-overhaul

07b3659

juanmaguitar added 2 commits August 19, 2024 09:32

Highlight Build, Test and Launch in the intro

1d10f10

Merge branch 'trunk' into docs/documentation-overhaul

3bbaab5

brandonpayton merged commit 02f31ca into WordPress:trunk Aug 19, 2024
5 checks passed

This was referenced Aug 27, 2024

Playground repositories overview #1270

Closed

Edit of the repositories overview page #1488

Closed

juanmaguitar mentioned this pull request Sep 12, 2024

Docs: Set redirection from old links to new links after Docs overhaul #1757

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

documentation structure overhaul #1602

documentation structure overhaul #1602

juanmaguitar commented Jul 11, 2024 •

edited

Loading

juanmaguitar commented Jul 11, 2024 •

edited

Loading

juanmaguitar commented Jul 11, 2024 •

edited

Loading

justintadlock commented Jul 11, 2024

adamziel commented Jul 15, 2024

adamziel commented Jul 29, 2024

adamziel commented Jul 29, 2024

richtabor commented Jul 29, 2024 •

edited

Loading

juanmaguitar commented Jul 29, 2024 •

edited

Loading

juanmaguitar commented Jul 30, 2024 •

edited

Loading

adamziel commented Jul 31, 2024

adamziel commented Jul 31, 2024

richtabor commented Jul 31, 2024

richtabor commented Jul 31, 2024 •

edited

Loading

juanmaguitar commented Jul 31, 2024 •

edited

Loading

adamziel Aug 9, 2024

adamziel commented Aug 9, 2024

justintadlock commented Aug 9, 2024

adamziel left a comment

adamziel commented Aug 18, 2024

adamziel Aug 18, 2024

adamziel Aug 18, 2024

adamziel Aug 18, 2024

adamziel Aug 18, 2024

adamziel Aug 18, 2024

juanmaguitar commented Aug 19, 2024

brandonpayton commented Aug 19, 2024

		@@ -0,0 +1,6 @@
		Merge branch 'docs/documentation-overhaul' of github.com:wordpress-juanmaguitar/wordpress-playground into docs/documentation-overhaul


		You can use Blueprints both with the web and the node.js versions of WordPress Playground.

		:::info Blueprints version 2

		@@ -22,20 +21,51 @@ The editor is under development and the embedded Playground sometimes fails to l

		:::

		## Check for the Filesystem and Database

documentation structure overhaul #1602

documentation structure overhaul #1602

Conversation

juanmaguitar commented Jul 11, 2024 • edited Loading

Motivation for the change, related issues

Implementation details

Testing Instructions (or ideally a Blueprint)

To-Do

juanmaguitar commented Jul 11, 2024 • edited Loading

juanmaguitar commented Jul 11, 2024 • edited Loading

justintadlock commented Jul 11, 2024

adamziel commented Jul 15, 2024

adamziel commented Jul 29, 2024

adamziel commented Jul 29, 2024

richtabor commented Jul 29, 2024 • edited Loading

juanmaguitar commented Jul 29, 2024 • edited Loading

juanmaguitar commented Jul 30, 2024 • edited Loading

adamziel commented Jul 31, 2024

adamziel commented Jul 31, 2024

richtabor commented Jul 31, 2024

richtabor commented Jul 31, 2024 • edited Loading

juanmaguitar commented Jul 31, 2024 • edited Loading

adamziel Aug 9, 2024

Choose a reason for hiding this comment

adamziel commented Aug 9, 2024

justintadlock commented Aug 9, 2024

adamziel left a comment

Choose a reason for hiding this comment

adamziel commented Aug 18, 2024

adamziel Aug 18, 2024

Choose a reason for hiding this comment

adamziel Aug 18, 2024

Choose a reason for hiding this comment

adamziel Aug 18, 2024

Choose a reason for hiding this comment

adamziel Aug 18, 2024

Choose a reason for hiding this comment

adamziel Aug 18, 2024

Choose a reason for hiding this comment

juanmaguitar commented Aug 19, 2024

brandonpayton commented Aug 19, 2024

juanmaguitar commented Jul 11, 2024 •

edited

Loading

juanmaguitar commented Jul 11, 2024 •

edited

Loading

juanmaguitar commented Jul 11, 2024 •

edited

Loading

richtabor commented Jul 29, 2024 •

edited

Loading

juanmaguitar commented Jul 29, 2024 •

edited

Loading

juanmaguitar commented Jul 30, 2024 •

edited

Loading

richtabor commented Jul 31, 2024 •

edited

Loading

juanmaguitar commented Jul 31, 2024 •

edited

Loading