Documentation Structure Block Editor Handbook

[tomdevisser]

After discussing some ideas for the Block Editor Handbook with @ryanwelcher, we thought the best next step would be to open a discussion for everyone to join in.

First of all, thanks everyone who is working on the documentation. I know it's a huge effort to get everything right and that the ratio of the team size and the amount of work that needs to be done is not common. Every feedback I have is based on potential I'm seeing, not to criticize anything that's been done so far.

The main documentation issue
The main issue I have with the documentation is how everything is so scattered, which is a result of having such a modular system with many different NPM packages. The generated docs are fine as a reference, but they're all isolated and I think we need a place that explains how these different packages work together.

It also has to be in a more chronological way, instead of taking a single isolated subject and putting everything there is to know, from beginner info to the most advanced inner workings, all on one page.

The Block Editor Handbook
I think the Block Editor Handbook would be the right place for this so that will be the focus of this discussion, but to be just that I think there needs to be some change in it's structure.

The Block Editor Handbook issues
One issue is with consistency, I think we need a place where we can see what words we're using, if we use British English or American English and how we capitalize stuff. A few simple examples: I see block Block block editor Block Editor etc. all over the place. It's also confusing to call something the Block Editor Handbook and then start the first sentence with Gutenberg. Question a lot of new devs will have: What is Gutenberg and what is the Block Editor, are they the same or not? Why are we getting all this phases info about Gutenberg when learning about the Block Editor?

The structure
Right now the structure has these chapters:

Especially for non-native English speakers, this can be confusing. E.g. what's the difference between an explanation and a how-to? And why is getting started not a how to? I know there are nuances in these words, but they're not super clear for everyone.

I rewrote an outline for a new structure. The main goals for this restructure are to take away some confusion, pointing people to other places when there already is a documentation (DRY), and create a chronological handbook people can follow, but still give them the opportunity to dive into deeper subjects right away.

- Introduction
- Prerequisites
    - Using React
    - Using Redux
    - Using NPM
    - Using PHP
- Getting Started
    - Development environment
    - Create a block (package)
- The Editor
    - Using the Editor
    - Extending the Editor
    - Site Editor vs. Block Editor
- Blocks
    - The anatomy of a block
        - Block Toolbar
        - Structure
        - Content
        - Sidebar
        - States
        - Setup
    - block.json
    - Block Attributes
    - Inner Blocks
    - Block Variations
    - Block Locking
    - Block Accessibility
    - Block Transforms
    - Block Patterns
    - Block Extensions
    - Dynamic vs. Static
- Reference
    - NPM Package Reference
    - Component Reference
    - Hooks Reference
        - Block Hooks
        - Editor Hooks
    - Core Blocks Reference
- Contributors (link to the guide on GitHub)

I would love to hear everyone's thoughts on this!

[StuurluiDevelopment]

@ryanwelcher @mburridge

[mburridge]

Thanks for this feedback @tomdevisser. You're absolutely right that the handbook should be more progressive in nature and that it should provide a gentler learning curve. Perhaps the Introduction to Block Development course over on learn.wordpress.org could be adapted to fit into the handbook in some way. Either a modified version of the course could replace the existing Getting Started tutorial, or the existing tutorial could be extended to cover more of the ground that the course covers.

Regarding the current structure of the handbook, it's loosely based on the Unified Theory of Documentation. The structure you suggest is a great start. I particularly like the idea of having a section on "The Anatomy of a Block". That's something that I think is lacking in the current handbook. Although I'm sure the information is in there somewhere it's quite dissipated and hard to assimilate, so that's a great idea. A section on the anatomy of a block would, I guess, fall under "Explanations" in the Unified Theory.

I think the Unified Theory of Documentation leads to well structured docs that is multi-purpose and serves a variety of users and learners, so we should be cautious of deviating too much from that model. However, within the structure of that model I agree that there's a great deal of restructuring that can be done to improve the docs both from a learning point of view and from a reference point of view.

[tomdevisser]

What is a good next step here? Mentioning it in doc meetings?

[johnhooks]

The structure you suggest is a great start. I particularly like the idea of having a section on "The Anatomy of a Block". That's something that I think is lacking in the current handbook.

As a developer new to Gutenberg / Block Editor (yeah, I don't know what to call it), the concept of "What is a Block" has taken a lot of exploration of the code base to figure out. I would also note the Block Attribute reference section could be a lot more detailed. I am very willing to help with this effort.

[mburridge]

Hey @tomdevisser, @johnhooks

Thanks for your suggestions and offer of help.

I'm currently undertaking an analysis of the handbook with a view to exploring how best to re-organise and/or restructure the content. I'm going to do this in the form of a mindmap so that we have a visual representation of how the handbook is now, so it will be easier to conceptualise and visualise how it can be made better.

If you're interested in getting involved with this I'd be delighted to have you aboard. Perhaps we could each target different sections of the handbook - I'm currently working through the Getting Started section.

Another job that I think is important is to identify what are the key concepts and knowledge that a developer new to blocks needs to learn. It would be great to get a list of these key things together with a view to ordering them into a structured learning path or curriculum of learning.

What do you think?

[mburridge]

Also, as I said earlier we should be cautious of producing documentation that isn't modelled on the Unified Theory of Documentation. The current handbook already follows that model of:

• Tutorials
• How-to Guides
• Explanation
• Reference

Though some stuff needs moving around, for example there are tutorials in the How-to Guides section, and I'm sure there's other stuff in the wrong place. Stuff can be changed, re-worked, and moved around, but largely within the strictures of the Unified Theory as they lead to good and well structured documentation.

[tomdevisser]

Is that your proposal, or is it a starting point that you intend to refine and develop further? It would be good to liaise together and work with each other.

A starting point, I'm sure we can improve it.

we should make sure that everything in the existing handbook is also in any new version

Definitely. We shouldn't "publish" a 2.0 (although I would rather call it 1.0 and the current one a beta) version before it's an improvement.

For the latter we would certainly need community support so go ahead and post in Making WordPress Slack.

Will do this on the next open floor!

Also, as I said earlier we should be cautious of producing documentation that isn't modelled on the Unified Theory of Documentation. The current handbook already follows that model of: tutorials, how-to guides (...) .

Although I think it's nice to have a reference, I don't think this should be regarded as our holy grail. Like with coding standards, we use common sense to make things more readable, and I immediately see a few fundamental flaws in the model of the "Unified Theory".

E.g. what is the difference between a tutorial and a how-to guide? And aren't they both explanations? And if I want to know how to do something, am I gonna scan the tutorials, explanations, how-to's or reference? Or all of them? It's not clear what goes where, which is why there's a lot of duplication and no way to see at a glance if something's missing.

[johnhooks]

Just from experience the tailwind.css, documentation is amazing. They actually make a point to repeat content so users don't have to back out of the current section to get context. @tomdevisser, I just want to throw it out there that duplication can actually improve the DX, as long as, it is relevant and correct.

I'll also commit to reading the current version cover to cover and document pain points.

[juanmaguitar]

I just want to throw it out there that duplication can actually improve the DX, as long as, it is relevant and correct.

While I agree it may improve DX, content duplication also brings maintenance issues that in the long term could introduce bigger DX problems (information not accurate or out of date).

[johnhooks]

@juanmaguitar I agree if the duplication is hand written. But I believe tailwind.css does it in code, so sections can be repeated, but not be a maintenance nightmare.

[estelaris]

My comments here from a design/UX perspective:

A few simple examples: I see block Block block editor Block Editor etc. all over the place. It's also confusing to call something the Block Editor Handbook and then start the first sentence with Gutenberg. Question a lot of new devs will have: What is Gutenberg and what is the Block Editor, are they the same or not? Why are we getting all this phases info about Gutenberg when learning about the Block Editor?

I see several problems here.

1. First identify when referring to a "block" as an item and when is "Block" as part of the name. The docs team has a style guide for this purpose.
2. Second, we are using a more international English, not too British, not too American. What that means is that we try to remove regionalisms as much as possible (like capitalizing every word in a title, "every two weeks" vs "fortnight"), use of simple language (e.g. async vs asynchronous). The goal is to help non-English speakers comprehend better what is written.
3. Third, there needs to be a content review to bring the documentation up-to-date (for instance, how long are we going to use the term "Gutenberg"?), clarify terms (difference between Block Editor and Gutenberg), etc.

I am not a fan of the Unified Theory of Documentation because it is restrictive, it doesn't allow for growth and software development needs a different structure when it is in continuous development. The structure proposed by @tomdevisser is a good starting point.

There are definitely no blockages in creating a new structure to the documentation if it is going to improve the DX. I suggest looking into the list of articles (documentation) available now and define where in the process each goes, which is pretty much what Tomas did.

[estelaris]

Happy to attend to, if I can be of any help. I have posted about this in #core and again in #docs. In my experience, peeps don't get too involved in the beginning but are great at giving feedback and suggesting changes once something is presented. Don't be discouraged, I can push on the changes from the docs side and get the right people involved as soon as we have something to show.
I'm in UTC +2

[mburridge]

@tomdevisser I presume you're in too? What timezone are you in?

[tomdevisser]

Definitely! I'm in Amsterdam, UTC+2

[mburridge]

Cool, thanks all 👌. I'll get something scheduled for next week at a time that accommodates as many of you as possible - it will probably need to be early-mid afternoon in Europe and morning in the Americas. What day would suit you best? How does Tue 04 Apr suit, at say 15:00UTC?

[mburridge]

Hey all, look below 👇

[mburridge]

I've set up a Zoom meeting to discuss restructuring / rewriting the handbook as per the forgoing discussion.

I've scheduled it for 15:00 UTC tomorrow 04 April 2023. Come with your amazing ideas, thoughts on what can be improved, and where you think there are gaps that need to be filled. All welcome.

I look forward to seeing you all and moving this project forward.

---

Zoom 3 is inviting you to a scheduled Zoom meeting.

Topic: Block Editor Handbook structure
Time: Apr 4, 2023 03:00 PM Greenwich Mean Time

Join Zoom Meeting
https://us02web.zoom.us/j/84021525365?pwd=NC9uVHQyMHEySUQwUU5teExKbFJaUT09

Meeting ID: 840 2152 5365
Passcode: 671588
One tap mobile
+13863475053,,84021525365#,,,,*671588# US
+15074734847,,84021525365#,,,,*671588# US

Dial by your location
+1 386 347 5053 US
+1 507 473 4847 US
+1 564 217 2000 US
+1 646 931 3860 US
+1 669 444 9171 US
+1 669 900 6833 US (San Jose)
+1 689 278 1000 US
+1 719 359 4580 US
+1 929 205 6099 US (New York)
+1 253 205 0468 US
+1 253 215 8782 US (Tacoma)
+1 301 715 8592 US (Washington DC)
+1 305 224 1968 US
+1 309 205 3325 US
+1 312 626 6799 US (Chicago)
+1 346 248 7799 US (Houston)
+1 360 209 5623 US
Meeting ID: 840 2152 5365
Passcode: 671588
Find your local number: https://us02web.zoom.us/u/kdRqVDwavu

[mburridge]

Please note: the meeting will be recorded.

[mburridge]

Apologies, please use this link to join the meeting: https://us02web.zoom.us/j/89687217223?pwd=Z01kTmNnWXlneEhMRXI0Y0lYL0llZz09

[mburridge]

I've uploaded the video from the meeting to YouTube. I don't think I'll have the time to write up the notes this side of the Easter break, but if someone else wants to have a go, feel free and post the notes as a reply to this.

[tomdevisser]

I'm very sorry for not attending, don't know if Michael shared it, but my dad got diagnosed with cancer this week so I've been working less and have been in another headspace. I firstly wanted to thank you all for holding this meeting and making a great start towards improving in my opinion one of the most important parts of the project. I'm watching the video right now and will finish it today so I'm up to speed with what has been discussed. Might drop some comments here later!

[tomdevisser]

Okay, watched the entire thing. First off, I think there's some really good ideas and insights here. It's super nice to see everyone has good ideas, and there seems to be a very much aligned vision on where we need to go, so that's great.

Having said that, I think the next meeting could use an approach that's a bit more pragmatic. There's been a lot of great ideas on content and pain points, but throwing them out there when we're not at a point where we can directly address them yet could lead to forgetting to address them at a later point, which would be a shame.

I think we need to divide this project into 3 stages.

1. Creating the structure (discussion overall hierarchy/structure)
2. Expanding the outline (discussion per subject)
3. Writing the content (discussion on low-level details)

For the next meeting I would suggest setting the goal of finishing the outline structure that I started in the initial post. Someone could share their screen and we can go over the structure and discuss what needs to be added/(re)moved/changed. This can still be changed, but it would be a 1.0 concept that we can then start working on. That would complete stage 1.

Once we have this actual outline, we can start making an outline per page/chapter. For example if we have the outline as mentioned above, we'd start with Introduction. What has to be on this page? What shouldn't be there? We can make a short list of questions we could ask ourselves and then go through all the chapters, Prerequisites, Getting started, etc. This is also the part where we can discuss all the problems and ideas that came up in this meeting, when we're actually at the chapter it relates to. This means once an idea or problem is mentioned we can come to a solution right away, instead of mentioning it and then thinking "yes we need to address that at some point". This would complete stage 2.

At this point we'll have a structure outline, plus a description of what should be on that page. This means we can start writing the actual content! We'll go over a few revisions and discussions once we have some content to discuss, and when this stage is done we have a perfectly thought out handbook. This would complete stage 3.

[tomdevisser]

@ndiego @mburridge @estelaris @fabiankaegy @carolinan Please see my comments above :) (couldn't find Jenni's GitHub handle, if someone knows it please include her here as well)

[tomdevisser]

One last addition to this, regarding the compartmentalizing suggestion Michael makes at the ending, I would highly recommend waiting with this until stage 2, and after every substep in stage 2 going back to stage 1 to see if the outline still works or if it could be improved. The biggest cause of most issues here, but also in WordPress (in my opinion), right now is compartmentalizing everything from the start and losing the bigger picture. Let's take a top down approach before working on low-level issues. I also wouldn't go async until the content writing stage.

[estelaris]

@jennimckinnon see above

[johnhooks]

My initial thoughts after watching the discussion:

• I agree the documentation needs to be versioned. Especially with the complexity of compatibility with Gutenberg and WordPress versions.
• There needs to be a distinction of the intended audience. I see at least three two:
  • General Audience - Non-technical users looking for usage information about the block editor.
  • Plugin Developer - Implementing of block plugins, needing documentation for a specific version of WordPress.
  • Gutenberg Developer - Working directly on the source code of the editor, needing the latest version of Gutenberg.
• Who is this document for? Can a single document actually target both audiences?
• If it is versioned, how can it be signaled to the reader they may be looking for documentation in the wrong location?
• As someone new to WordPress the fragmentation of documentation has been a struggle. Its compound by the way Gutenberg is published in packages versioned totally separate from the Gutenberg package. It's not at all apparent when beginning block development and installing @wordpress/components into a project, the version indicated in the package.json has no effect on the build asset. It enqueues wp-components which will be whatever version was included in release of WordPress that load it, or Gutenberg if installed.

As a developer, I am most interesting in a detailed, versioned, interlinked, and searchable API reference (anything like the Code Reference would be a huge improvement). To make sure it stays up to date I would think it needs to be part of the release cycle and most of it generated from JSDoc comments.

[estelaris]

@johnhooks the documentation in this handbook is focused on developers, in general and Gutenberg/Block developers in particular. Although we cannot hold anyone from reading the documentation, it is not written for a general-non-technical audience. There is the end-user documentation for the general-non-technical audience.

[johnhooks]

Thank you @estelaris I struck general audience.

[johnhooks]

I understand there is a difference between a good API reference and the Handbook, but the handbook is where the current Block API reference is located. Like @ndiego and @fabiankaegy, I find myself looking through the Gutenberg repository for basic information which should be in the reference. Thought because the README.md files are not interlinked, it can be a struggle to jump from the documentation of one package to the next. It also requires checking out the appropriate git release branch to make sure the documentation and code is from a specific version.

Should pursuing this goal be separate from the Handbook, just in the same way the WordPress Code Reference is independent from its Handbooks?

[estelaris]

I am adding the following comment from @alexstine in here, as a reference for the changes we are suggesting, he has good points regarding accessibility that will be handy when we review content

I just wish blocks for developers were documented better. I do not find it useful that I need to adjust the block in the editor and then copy the code into a block theme. Why not instead tell me which blocks have which attributes and let me adjust it myself? There is a dependency on the block editor that makes development harder and the evolution of this concept is kind of scary. Why create block themes at all when in reality, the editor does all the work? It will lead to an impressive set of problems down the road as users getting near certain areas of websites never ends well. I like the idea of being able to output certain blocks by typing the HTML-like code because it is a lot of how PHP still works. Call the function, outputs some value. That is simple enough to understand. Docs in most places around core functions are good and if not, the source code is viewable right on codex.
Related doc: https://developer.wordpress.org/themes/block-themes/templates-and-template-parts/#how-to-find-which-block-markup-to-use
Anyone else find this lacking? Of course for me, this is slightly more annoying due to the accessibility of some of these blocks. I just figured for all devs this may get annoying after a while to require the block editor to do what could be done in minutes with PHP/HTML. Might be an unpopular opinion but I guess I am kind of good at that lately.
Compared with: https://developer.wordpress.org/reference/functions/get_the_title/

It is also worth saying, developing Gutenberg on Windows is possible. I do it. You can use WSL for all the Linux parts. Handles Node.js a lot better than Windows Node.js installer. If it is just a case of having older Mac, I can see where that may be a problem. Building the project takes some resources. I prefer building on my Mac but all hope is not lost for our Windows users. I use both for dev.

[alexstine]

Adding to this, it is not an accessibility concern alone as much as it is a development concern. No developer wants to waste time in the block editor when they could simply open the docs and know exactly how to build the proper JSON structure in templates. Gutenberg is a JSON generator, it is what it does in practice. That does not mean there should not be docs around what each attribute does. WordPress is really how I learned PHP because the project is documented so well. I hate to see Gutenberg move us away from helpful learning materials.

[ndiego]

Hi @alexstine, I want to make sure I understand correctly. Using the Columns block as an example, the block includes the option to disable stacking on mobile. If toggled, the attribute "isStackedOnMobile":false is added to the block. Are you referring to better documentation on how each of these attributes work?

The Core Block Reference does indicate all of the custom attributes for core blocks, but it doesn't go into any detail beyond just listing the attributes.

[alexstine]

@ndiego Yes, that is exactly what I am after. Something with details. Take this example page.

https://developer.wordpress.org/reference/functions/get_the_title/

Now, instead of PHP, think about how this format could work for each block.

Columns block
Description of the block.
Documented block attributes
Examples
Source Code on GitHub

Having everything on 1 page also feels a little overly messy to me especially given how the project will progress in the future.

Thanks.

[carolinan]

Especially for the block attributes, the current reference does not give enough information; it doesn't even say if it's a string or a boolean, etc. It doesn't give an example of how or even if that attribute is written in the block markup.