Plan proposal for a new better structured Gutenberg developer documentation

Welcome to the official home of the WordPress documentation team.

This team is responsible for coordinating all documentation initiatives around WordPress, including the Codex (moving to HelpHub and DevHub), handbooks, parts of developer.wordpress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/, admin help, inline docs, and other general wordsmithing across the WordPress project.

Want to get involved?

There are many ways in which you can help the Docs team. Every small contribution counts and helps! You can report an issue or typo you found in the docs, or even help us write new documentation for parts that are still missing. These are some helpful links to find out more about what we do and how to collaborate:

Docs Team Handbook: An overview of what we do and how to collaborate
Block Editor Handbook: An overview of documentation contributions of 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 / 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.wordpress.org: The home of the developers’ documentation
wordpress.org/support: The home for all end-user documentation

Weekly Meetings

Join our discussions of documentation issues here on the blog and on Slack.

The documentation team holds weekly office hours on Mondays from 14:00-15:00 UTC in the #docs SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channel.

Although we have a fixed schedule of weekly meetings, you can contact the Docs Team at any time through our Slack channel.

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

Marcus Kazmierczak 6:08 pm on August 13, 2020

I consider this page: https://developer.wordpress.org/block-editor/ the home page 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 documentation, and not the level you link to. This gives more context about the project, and links to sections across the entire project.

The source of the documentation in the Block Editor Handbook is published from the 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/ docs folder in the repository: https://github.com/wordpress/gutenberg as well as generated from the packages contained there also. A process is run every 15 minutes to sync changes.

More information on the process and docs are available in the Documentation contributor guide in the Block Editor Handbook here: https://developer.wordpress.org/block-editor/contributors/document/

Look forward to working with you on improving, and getting more contributors to the Block Editor Handbook and 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/ documentation.
- Justin Ahinon 5:29 am on August 14, 2020
  
  Thanks for the clarification Marcus and for offering your help.
  
  Looking at the general structure https://developer.wordpress.org/block-editor, yeah it makes more sense to use it to have an overview.
  
  The contributor docs is very useful. Actually, I thought before that the developer docs lives on w.org as the end user docs.
  
  Right now, I’m looking for ways to make this post reach more people who could be interested. So, I’ll wait a couple of weeks and then make an update.
Milana Cap 8:43 am on August 14, 2020

+make.wordpress.org/core/
annezazu 4:53 pm on August 14, 2020

Thanks for this post. Keen to help here as I can whether it’s organizing efforts, helping gather information (similar to 5.5 Q&As), or doing updates directly. I’ll stay tuned for more as I very much agree this should be as useful as possible to newcomers.
- Justin Ahinon 6:34 pm on August 14, 2020
  
  Nice you’re offering to help Anne :). I think this project will need a lot of outreach and communication efforts with the teams, and it’ll hugely benefits from your experience.
  
  My plan now it to collect comments about the post for a couple of weeks, and then reach out to people who manifested their interests.
  
  But I’ll definitely get in touch with you sooner (probably next week.. I’m about to logout for the weekend now).
  
  Thanks 🙂

WordPress.org