documentation structure overhaul

[juanmaguitar]

Motivation for the change, related issues

This PR (still in draft) is related to the issue https://github.com/WordPress/wordpress-playground/issues/1518

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

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

[juanmaguitar]

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

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

https://github.com/WordPress/wordpress-playground/assets/422576/edb06ff4-87c4-4052-822d-eec4fa0c9787

[justintadlock]

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]

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

[adamziel]

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

[adamziel]

Also, any updates here @juanmaguitar?

[richtabor]

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]

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.

https://github.com/user-attachments/assets/437a9929-3d78-4c0c-9099-0d9c06539768

[juanmaguitar]

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]

Yay, lovely work here!

[adamziel]

Surfacing this issue as it's relevant here https://github.com/WordPress/wordpress-playground/issues/1529

[richtabor]

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

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

[juanmaguitar]

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 https://github.com/WordPress/wordpress-playground/issues/1663 and https://github.com/WordPress/wordpress-playground/issues/1664 to gather feedback around these guides

[juanmaguitar]

Surfacing this issue as it's relevant here https://github.com/WordPress/wordpress-playground/issues/1529

@adamziel I added these suggestions to the TO-DO section of the description of the issue. I'll tackle these suggestions tomorrow.

[juanmaguitar]

@adamziel, this PR is finally ready for review. I have updated the description with a video showcasing how it would look like the Playground docs with the changes on this PR.

[adamziel]

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.

[justintadlock]

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]

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.

[juanmaguitar]

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]

@juanmaguitar Sure thing. Done!