Block Editor Handbook: restructuring project update (March 12)

This is the third update for the project to restructure the developer documentation of the blockBlock 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. editor. You can find the first update here and the second here.


During the whole month of February, we worked on restructuring the table of contents of the block editor developer documentation. It was a long process, and we had to think about the best possible organization to bring more consistency to the entire documentation.

We chose to structure the table of contents according to the different needs that a person might have when coming to the documentation; and also according to the stage that this person is at in using or learning the block editor.

For example, someone who is new to development for or with the block editor would be looking for a tutorial on how to quickly set up a development environment, and quickly create a block. While an experienced developer with the block editor might be looking for more advanced concepts like package documentation. A designer who wants to start contributing to the block editor would look for a contribution guide.

These are just some of the use cases that will direct a person to a particular section of the documentation or another.

The new documentation structure was therefore largely inspired by Divio’s “Documentation System” concept. The idea is to build technical documentation around four parts: tutorials, how-to guides, technical reference and explanation.

Each of these parts has a specific function and is intended for a given group of people.

We have merged a couple of days ago the pull request for restructuring the table of contents. We will continue to make changes to iterate on everything we have done since then.

Here is the transition from the old table of contents to the new one:

Block editor handbook table of content transition

For more context, check the pull request and the related issue on GitHubGitHub 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/.

You can expect a wrapping up post for the project in the coming days/weeks.


Props to all the people who have contributed to this project til now:
@paaljoachim, @annezazu, @omarreiss, @mkaz, @youknowriad, @DaisyOlsen, @mtias, @priethor, @gziolo, @ntsekouras, @aristath for their feedbacks and inputs; and @coffee2code for helping on handling the various MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. related tasks for the DevHub website.