Over the last year, a group of contributors has been working to improve the block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. development onboarding experience within the Block Editor Handbook. In this post, I wanted to take a moment and highlight the updates made, pinpoint areas for further refinement, and outline our focus for the next few months and ways you can help.
Project overview
The initiative to enhance the Block Editor Handbook began in 2020, largely sparked by the Next Steps for Block Creation Documentation discussion on GitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/. Since that time, the community has been consistently updating the content, with the most recent effort led by @juanmaguitar, @welcher, @mburridge, and myself.
You can view the tracking issues here:
In talking with prospective block developers, documentation was consistently one of the most recurrent pain points, especially for those who want to learn how to build custom blocks or extend the Editor using official resources. Improving the Getting Started section, as well as other extensibility docs, was a natural starting point in addressing this feedback.
Here are some highlights from the work completed in the last eight months:
- Landing page makeover: We’ve revamped the Handbook’s main page to make it more inviting and informative for those new to block development.
- Updated Getting Started chapter: This section now offers a clearer path for beginners, including:
- Expanded Curating the Editor Experience: Previously a single page, this topic was given its own dedicated section, with more updates coming in Q1 2024.
- Block Development Examples: We launched a GitHub repository filled with practical examples of custom blocks and Editor extensions, complete with Playground previews and downloadable versions of each example. Contributions to the repository are welcomed.
- More visuals: We’ve added diagrams and images throughout the Handbook to clarify key ideas.
Next steps
There is still plenty of work to do on the Getting Started chapter. A few additional articles for the Fundamentals section are in the works, and the Glossary and Frequently Asked Questions articles need updating. Following that, the How-to Guides chapter is the top priority, followed by Explanations.
At this point, improvement to the Reference Guides chapter is ongoing, but no fundamental restructuring is planned in the near future. If you have ideas on how this section can be improved (much of it is autogenerated from in-code documentation), please share your suggestions. The current setup is not ideal, and it’s also not complete. Some code documentation is only accessible in the Gutenberg GitHub repository.
Get involved
The Block Editor Handbook contains over 400 published pages, and the effort taken in 2023 just scratches the surface. While that might seem daunting, improving the documentation is one of the easiest ways to contribute to the WordPress project, especially for quick fixes like typos or formatting. Feedback on existing content, such as the new block tutorial, is also invaluable.
All documentation is hosted on the Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ GitHub repository. If you find an issue or wish to give feedback, please open a new issue there. If you would like to fix issues yourself, follow the Documentation Contributions guide to learn how to submit a pull request. You can see the list of all outstanding documentation issues using the [Type] Developer Documentation label.
If you experience any problems or have questions, reach out in the #core-editor or #docs Slack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channels. You can also leave comments here or ping The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me (@ndiego) directly.
Props to @greenshady for reviewing this post.
+make.wordpress.org/docs/
#block-developer-experience, #developer-documentation
