search

WordPress / wordpress-playground

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

Suggestions for improving the WordPress Playground 'Get Started' documentation page #1274

Open AnneYoast opened 5 months ago

AnneYoast commented 5 months ago

WIP! Group effort by Manuel (@manuelaugustin) and I!

At the top of the page, clarify the purpose, audience and 'learning objective' of this page and the wider documentation. This would give users a clear idea on how to navigate the entire documentation.

I.e. 'This page introduces the functionalities of WordPress Playground for all users, from people new to the application to experienced developers. By the end of this page, you know the basics of WordPress Playground and where to find information in this documentation to use WordPress Playground.'

First, define WP Playground in one paragraph or so; perhaps summarise the Overview page, or take its first paragraph instead.

AnneYoast commented 5 months ago

The overall structure does not cater to a 'learning journey' and navigation is not intuitive.

How about redividing it into:

adamziel commented 5 months ago

100% agreed and I love that structure 💯 One thing I struggled with was splitting it into "learning journey", "how-tos", "tutorials", and "developer reference" – the current doc intertwines all these ideas and isn't very helpful.

AnneYoast commented 5 months ago

Yessss those ideas are all very very close! And catering to so many types of audience is also difficult. There's so much great stuff in there, I do really want to emphasise that, but structuring it for people encountering for the first time when you're knee-deep in the sauce is the most difficult!

AnneYoast commented 5 months ago

Something that I'm missing is an introduction to Blueprints! Maybe a short article under the proposed 'How to get started' section would be good; currently there's only a deep dive under API.

AnneYoast commented 5 months ago

Proposal for WordPress Playground Documentation page.docx

I've attached a proposal for a new Introduction page, i.e. the page that opens the entire Documentation section.

adamziel commented 5 months ago

Something that I'm missing is an introduction to Blueprints! Maybe a short article under the proposed 'How to get started' section would be good; currently there's only a deep dive under API.

Yes! This one could be included or linked to: https://github.com/adamziel/blueprints/blob/blueprints-crash-course/docs/index.md. Also @ironnysh wrote this amazing introduction to WordPress Playground that also discusses them.

adamziel commented 5 months ago

I've attached a proposal for a new Introduction page, i.e. the page that opens the entire Documentation section.

Lovely! One thing I was thinking about was having a few sections like "I'm a site builder", "I'm a theme designer", "I'm a plugin developer", "I'm exploring innovative apps", "I want to contribute" etc and then have a few bullet points with links out to relevant sections of the documentation, e.g. "Test your site on different PHP/WordPress versions". That's more in the "how-to" area, though, and less in the "I want to get from zero to a good understanding of what Playground is".

AnneYoast commented 5 months ago

I like the blueprint article you've attached, that'd be really useful! I also love the introduction article, but I'd maybe add that in the How to get started with Playground section?

As for the specific sections, I'm a bit hesitant on including all those separate groups on the introduction page.

adamziel commented 5 months ago

I also love the introduction article, but I'd maybe add that in the How to get started with Playground section?

👍

As for the specific sections, I'm a bit hesitant on including all those separate groups on the introduction page.

Tell me a bit more – do you think that would be too distracting?

flexseth commented 4 months ago

@AnneYoast

What is WordPress Playground?

WordPress Playground is an online platform that allows you to experiment and learn about WordPress without affecting your live website.

Probably the biggest benefit of running the Playground is you can experiment without having to worry about risking installing software or anything else to see WordPress

It's a virtual sandbox

100% on brand. The sandbox idea and the greater idea of the Playground being approachable to all audiences is what we're going for. Including all age ranges. Bravo.

in support of these changes, please see

Happy to work with you all to craft a few pages, please see the issue I opened based on your feedback. I think we can be a little more inviting to brand-new users of the Playground.

@ironnysh's article awesome, a bit technical though. Let's call it "Developer Friendly" :)

I don't see any problem with having different voices in the Developer Blog Post and the docs here, at all. Just makes it more voices contributing.

If you all want to look at some outlines for the onboarding pages (I, we, Adam, Ronny) - I believe - would be more than happy to have you contribute to the Playground documentation!!

Please check out the proposal I raised in the issue above, the idea is to re-structure this repo a little bit. There's probably more that needs to be done in the other repos, too... but we can start here.

Those who have worked with the Playground for a bit can work on the more technical documentation... if you all would be interested in some of the end user docs...