search

WordPress / gutenberg

The Block Editor project for WordPress and beyond. Plugin is available from the official repository.
https://wordpress.org/gutenberg/
Other
10.5k stars 4.19k forks source link

Docs: Update the Getting Started section to provide a better developer experience #54124

Open ndiego opened 1 year ago

ndiego commented 1 year ago

This issue tracks improvements to the Getting Started section of the Block Editor Handbook.

Getting Started is arguably the most important section of the Handbook. It aims to provide an onramp for developers who are new to working with the Editor and/or blocks. Currently, the section contains very outdated information and needs to provide a better learning pathway.

The project will include rearranging existing docs, removing outdated content, updating everything, and adding new docs to illustrate the essential concept of block development. The resulting structure will look quite similar to what currently exists but with updated content and an improved flow.

All content updates will also focus on referencing existing developer docs, Learn WordPress courses/material, and the WordPress Developer Blog articles for additional information. Let's cut down on content duplication as much as possible.

Section structure

Getting started

Tasks

Content to be moved or removed

Content to be updated

New content

juanmaguitar commented 1 year ago

Remove Create a Block Tutorial and all subpages (content will be repurposed/replaced with updated guide)

This tutorial is linked from several articles (see https://richtabor.com/publish-blocks/ for example) so I would redirect this URL https://developer.wordpress.org/block-editor/getting-started/create-block/ to a page (or section within a page) that recommends tutorials or courses (within wordpress.org) to start with Block Development

juanmaguitar commented 1 year ago

This is the diagram we're using to organize how do we think ideas should be distributed along this section (please, feel free to chime in and share your thoughts) https://excalidraw.com/#room=8c538e461500a1fe8523,7pSlj3w0awiHsHxiWS6tCw

PS: Right now the diagram only reflects the changes on the "Block Development Environment" section but it will be expanded with ideas on the whole Getting Started section

image

colorful-tones commented 1 year ago

This is the diagram we're using to organize how do we think ideas should be distributed along this section (please, feel free to chime in and share your thoughts)

@juanmaguitar, was this something we wanted more extensive WordPress community engagement around? I'm happy to share and amplify.

juanmaguitar commented 11 months ago

@juanmaguitar, was this something we wanted more extensive WordPress community engagement around? I'm happy to share and amplify.

Hi @colorful-tones, more feedback is always welcome although this revamped getting started guide aims to address feedback shared during the last years at https://github.com/WordPress/gutenberg/issues/22151 as explained in https://github.com/WordPress/gutenberg/issues/55432

Issues are available for the different pages planned to improve the onboarding experience so feel free to chime in and share your ideas on them. PRs for these issues are coming so comments can also be made over these more specific content proposals.

We can also iterate on them once they're published.