Follow up on Gutenberg developer documentation restructuring proposal

The proposal to restructure GutenbergGutenberg 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/’s developer documentation was discussed a few weeks ago during the weekly JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. office hours (rollback to the discussion here, meeting notes here).

We agreed that it makes sense to clearly identify stakeholders and use cases of the documentation before any action is taken.

This information has been collected in this Google Docs document.

The main stakeholders identified are:

  • Site developers: people who create WordPress sites with custom themes and plugins.
  • Site builders: people who create sites with primarily a page builder, or a theme that includes a page builder.
  • Theme Authors: Developers of WordPress themes, hosted on the official theme directory or elsewhere.
  • PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party authors: WordPress plugin developers.
  • WordPress Core contributorsCore Contributors Core contributors are those who have worked on a release of WordPress, by creating the functions or finding and patching bugs. These contributions are done through Trac. https://core.trac.wordpress.org.: People who contribute to the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. of WordPress, to Gutenberg, etc…
  • Content creators: People who create content on WordPress sites.

For each of these stakeholders, the nature of the expectations are different. Theme developers or contributors to WordPress want to be able to alter the way 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 works, its structure or presentation; while site builders and content creators expectations will be best met by the user documentation for the block editor.

Next Steps

The major use cases that emerge from all those in the document mentioned above are:

  • Update/alter the UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. or the structure of the editor and its elements
  • Create blocks for the block editor
  • Create block patterns
  • Programmatically modify or trigger the functioning of the block editor and its elements

The next steps to move forward could be to propose a structure around these major use cases.

You can do this as a comment to this article. This will also be on the agenda for the next JavaScript office hours.

#block-editor, #developer-documentation

Plan proposal for a new better structured Gutenberg developer documentation

I’ve recently volunteered to be the GutenbergGutenberg 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/ developer documentation team repTeam Rep A Team Rep is a person who represents the Make WordPress team to the rest of the project, make sure issues are raised and addressed as needed, and coordinates cross-team efforts..

This is a proposal of next steps for a friendly Gutenberg developer documentation, useful for newcomers.
For more context about the current state about Gutenberg dev docs, and its challenges, read this: https://wptavern.com/wordpress-contributors-seek-sponsorship-for-improving-gutenberg-developer-docs.

The plan is to build on the existing documentation (https://developer.wordpress.org/block-editor/developers) to arrive at a better structured doc.

Here are some aspects that I thought the team could focus its discussions and reflections to get started.

Where are we at now?

It is essential to have an overview of existing documentation. Both the one present on https://developer.wordpress.org/block-editor/developers, on GitHub (if there is any), and also those in progress. This is to avoid dispersing our efforts, and to take advantage of the work already done by other contributors and volunteers.

What should be included?

In my view, one of the first step would be to agree on what should be included in the new documentation. There are currently many concepts (CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. concepts, APIs, etc…) that can be useful for developers using 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. Some of them are already present in the current documentation. Others are in the codebase on the project’s GitHubGitHub GitHub is a website that offers online implementation of git repositories that can 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/ repository.

A new structure?

The current structure of Gutenberg’s developer documentation is one of the aspects that makes it not friendly at all. For example, the home page of the documentation starts with the chapter “Creating Blocks”. A beginner is like thrown into the cauldron without knowing the prerequisites. Several contributors also address the question on GitHub here https://github.com/WordPress/gutenberg/issues/22151.

In this regard, I think we could learn from examples of documentation such as Gatsby.js https://www.gatsbyjs.org/docs (a quick start/tutorial, then a reference guide that discusses key concepts in a more or less defined order).

Cross-team collaboration

How do we want to collaborate with the different teams to make this happen? From here I see the core-editor team playing an important role, given their experience with the block editor development.

What’s next?

At this stage, we are only at the discussion stage, to see what is feasible and the best way to do it. If you are interested in helping with any of the steps, please feel free to comment. Also, if you have other points that you think are essential or need to be discussed in this plan, please feel free to mention them in your comments.

Season of Docs 2020

With the Season of Docs starting in a few weeks, I think this could be a great opportunity to move forward on that plan.

There are two projects in particular that could help:

  • Project #6 with @kenshino: Improve Existing Development Documentation and Handbooks and
  • Project #8 with @milana_cap: Extending Block Editor.

#block-editor, #documentation