-
Notifications
You must be signed in to change notification settings - Fork 252
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
documentation structure overhaul #1602
documentation structure overhaul #1602
Conversation
@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.
|
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 |
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. |
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 💯 |
It would be highly useful to visibly the Blueprint gallery from the Blueprints section |
Also, any updates here @juanmaguitar? |
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. |
@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 |
@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 |
Yay, lovely work here! |
Surfacing this issue as it's relevant here #1529 |
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
1
Outdated
@@ -0,0 +1,6 @@ | |||
Merge branch 'docs/documentation-overhaul' of github.com:wordpress-juanmaguitar/wordpress-playground into docs/documentation-overhaul |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can remove this file
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]>
Co-authored-by: Adam Zieliński <[email protected]>
Co-authored-by: Adam Zieliński <[email protected]>
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 🎉
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. |
|
||
You can use Blueprints both with the web and the node.js versions of WordPress Playground. | ||
|
||
:::info Blueprints version 2 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice!
@@ -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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
❤️
@@ -22,20 +21,51 @@ The editor is under development and the embedded Playground sometimes fails to l | |||
|
|||
::: | |||
|
|||
## Check for the Filesystem and Database |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm really happy to have this section in the docs. Thank you!
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yay! This is another lovely and useful nugget
- [**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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🩷
@brandonpayton I have solved the conflicts. The PR is ready to be merged but I cannot merge it. |
@juanmaguitar Sure thing. Done! |
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-5a11323d1282Implementation details
This PR creates three different subsites to organize three big types of docs related to WP Playground:
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)
npm run build:docs
npm run dev:docs
To-Do
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