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

[AnneYoast]

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]

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

How about redividing it into:

• Introduction (Start here, Overview)
• How to start using WP Playground (Start Using WordPress Playground in 5 minutes, Build your first app, Limitations - if you are a user)
• APIs (Playground APIs, Blueprints API, Query API, Javascript API)
• For developers (Usage in Node.js, Architecture, Limitations - if you are a developer)
• Contributing (WordCamp Contributor Day)
• Links and Resources
• FAQ

[adamziel]

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]

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]

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]

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]

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]

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]

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]

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]

@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

• Revamp WordPress Playground repo home page #1277

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...