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

[ndiego]

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

• Block Development environment
  • Node.js development environment
  • Get started with wp-env
  • Get started with wp-scripts
  • Get started with create-block
• Quick start guide
• Create a block tutorial
• Fundamentals of block development
  • Anatomy of a block
  • Static vs. dynamic blocks
  • More docs can/should be added as needed (block.json, components, etc.)
• Frequently asked questions
• Glossary

Tasks

Content to be moved or removed

• Move Glossary to Getting Started
  • Docs: Move Glossary page to Getting Started. #54120
• Move FAQ to Getting Started
  • Docs: Move the FAQ page to Getting Started. #54117
• Remove Full Site Editing and move any relevant information to other docs
  • Docs: Remove the Full Site Editing doc. #54516
• Remove Outreach and move any relevant historical information to the History doc
  • Docs: Remove Outreach doc from Getting Started section #54314
• Remove Create a Block Tutorial and all subpages (content will be repurposed/replaced with updated guide)
• Remove How to setup local WordPress environment on Ubuntu and add this info to the new wp-env guide (see below)
  • Docs: Overhaul the Development Environment section of the Block Editor Handbook #54395

Content to be updated

• Update Glossary
• Update FAQ
• Update Developer Environment and break out the wp-env guide into a separate doc
  • Docs: Overhaul the Development Environment section of the Block Editor Handbook #54395
• Update main Getting Started doc to reflect the planned changes

New content

• Add a dedicated doc for setting up a local dev environment with wp-env (subpage of Developer Environment)
  • Docs: Overhaul the Development Environment section of the Block Editor Handbook #54395
• Add a dedicated doc for getting started with create-block (subpage of Developer Environment) #54960
• Add a dedicated doc for getting started with wp-scripts (subpage of Developer Environment) #54961
• Add a new "Quick start guide"
  • Add new block development "Quick Start Guide" and update the create-block-tutorial-template #56056
• Add a new "Create a block tutorial" #56305
• Add a new section for "Fundamentals of Block Development" #56282

[juanmaguitar]

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]

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

[colorful-tones]

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]

@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 #22151 as explained in #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.

[annezazu]

Is this still being worked on?

[ndiego]

Not actively. I'll close this out, and we can open new issues as needed.