Discussion: documentation handbook plans for site editing and beyond... 🚀

[mkaz]

What name should we use for developer documentation handbook for the Gutenberg projects?

This topic was raised first by @zzap in this Make Docs post and then brought up again in this week's #core-editor chat.

One issue is the docs from the gutenberg repository are published to the "Block Editor Handbook" at https://developer.wordpress.org/block-editor

Historically, the name and reference to "Block Editor" implies the Post Editor, the block editor phrase is used throughout our developer and user documents to refer to the Post Editor. With the future release of a Site Editor, Widget Editor, and Navigation Editor does the "Block Editor" name for the handbook still make sense?

Additional issues are that full site editing will span multiple handbooks across WordPress, for example looking at the DevHub landing page, we need to make it clear how to find information developers are looking for:

My suggestions are:

1. Rename the Gutenberg docs published from this directory to a "Editor Handbook"
2. Add a new index page within Editor Handbook covering links to the various Site Editing projects
3. Update handbooks with relevant info, and cross-link in both directions, so wherever someone starts they can find what they need.
4. Group documentation within Editor Handbook with multiple editors in mind

This issue is intended as a discussion place as the original post by Milana did not garner much traction, or actionable items. So an attempt to spur additional, I welcome your thoughts and comments. 🙏

Related:

• Site Editor naming: Site / Template editor welcome guide #29031

[paaljoachim]

Block Editor Handbook in its name does also cover the Full Site Editing experience. As FSE would just be a new chapter/section in the Block Editor Handbook. Along with special mentions of the Widget screen, Customizer, Navigation screen, and any other wp-admin screen that gets blockified.

So my suggestion is to keep the name Block Editor as it includes any feature that uses blocks.

It is really just our minds where we need to embrace an expanded definition of the name Block Editor Handbook.

[mkaz]

Yes, I think you might be right, Block Editor is a generic enough term that it can cover the various editors: Post Editor (it also does Pages), Site Editor, Widgets Editor, Navigation Editor, and probably more to come.

However, the term "Block Editor" has been used consistently since the 5.0 launch to refer to the Post Editor. You can see this in user documentation here and also in plenty of internal and external sources including blog posts, videos, and plugins. A quick search turns up hundreds of results.

It is fine to update and change since the project has grown, and all the editors are block editors used to edit different content be it a Post, Page or Site. I think we just need to be mindful on naming and how we are documenting, so we can be clear to users and developers what parts we are talking about.

[paaljoachim]

The "Block Editor" term which has been used up to this point is as you say focused on the Post Editor. As things change the definition will also naturally change.

This also means that talking about the "Block Editor" in relation to example Full Site Editing and other places. One could then mention something like the Block Editor in Full Site Editing, the Block Editor in the Navigation Editor, etc. Bringing the terms together. Down the road one might also say the Block Editor in the Dashboard screen. The Block Editor in wp-admin. As the Block Editor is a generic term to be used along with the area/another editor being talked about.
In a couple of years one might say the Block Editor in the Post Editor, as the term has expanded. But for a while talking about the Block Editor with no reference to another Editor screen will imply the Post Editor screen.

I am thinking @mtias and @jasmussen might have some additional thoughts here.

[DaisyOlsen]

I've been pondering this topic for a bit, as I have been thinking quite a lot about the structure of the developer docs for block themes. I don't have any conclusions, but I have some thoughts taking shape.

One challenge I'm seeing with several areas related to developing for the block editor is that end user docs feel like dependencies to code reference docs. In a lot of cases, using the editor is an early step in coding for the editor. This is true for block patterns, block theme templates, and block theme template parts.

If we change to "editor handbook" is there any existing or planned content that would no longer make sense in this area? As we build better docs for Block Themes, should we move them to another area? A separate place or included in the theme handbook?

Until now it's been helpful to have the docs related to a rapidly changing part of WordPress somewhat isolated from other documentation that's more mature in its development. I'm not sure that the rapidly changing aspect is likely to change soon.

I wonder if there is merit in the idea of having a dedicated Gutenberg handbook that is written based on the features under development and use it to get an earlier start on docs for what lands in core and also get the docs into the hands of extenders earlier? That seems to be the original intent of the Handbook as it is currently implemented. I could see maintaining the current handbook as the "Gutenberg" handbook and beginning to curate a new Editor handbook for things already merged into core.

The biggest problem I see in the idea above is the difficulty of keeping up with changes in Gutenberg. I will say that I think there could be some hesitancy to document things that are only in the plugin not only because they may change quickly but also because they are not in core and there is confusion about who exactly that handbook is written to assist - extenders working with core for production or extenders working with Gutenberg to prepare for what's under development or coming soon.

[jasmussen]

Lots of thoughts here. A few high level thoughts:

• The editor is called the block editor. Whether it's used inside the post editing screen, or the site editing screen.
• We naturally refer to the post editor as the post editor, but the term isn't actually surfaced in the UI. There, it's "Add New Post".
• It's possible in the future that there won't be a separate Site Editor menu item, even for block themes, that you would need to go in there through other avenues, such as directly from the post editor.
• It's equally likely that the item remains, but get renamed or moved. It could be a submenu item under "Appearance".

In both cases, I would not optimize too heavily for how things work today, especially so long as we have the "Beta" tag attached. I know there's an extra layer of difficulty, to Daisy's point, with keeping up with the changes. To me that says use existing terms when possible, instead of looking too far ahead.

[annezazu]

Thanks so much for kicking off this discussion and driving this forward 🙌🏼 I have a few high level thoughts to the suggestions you shared:

Rename the Gutenberg docs published from this directory to a "Editor Handbook"

I was originally convinced that this is a solid direction to go in. However, based on the feedback above, I'm convinced otherwise that it's okay for now to keep the name as is. I also worry a bit about any potential SEO hits there.

Add a new index page within Editor Handbook covering links to the various Site Editing projects
Update handbooks with relevant info, and cross-link in both directions, so wherever someone starts they can find what they need.
Group documentation within Editor Handbook with multiple editors in mind

All of the above sounds great to me as a starting point until things naturally might need to break off if they become larger projects. Having an initial "landing page" for documentation too will be extremely advantageous for getting the word out as adoption of various aspects of FSE picks up speed.

[carolinan]

• It's possible in the future that there won't be a separate Site Editor menu item, even for block themes, that you would need to go in there through other avenues, such as directly from the post editor.
• It's equally likely that the item remains, but get renamed or moved. It could be a submenu item under "Appearance".

These are the discussions that need to be public, clarified, and finalized.

[jasmussen]

All of those are public, they are comments on github issues right here.

[carolinan]

Is that enough if contributors are not able to clearly see the direction? Is there an overview issue that I have missed?

[jasmussen]

This is the overview issue: #24551, and there is a conversation about the menu item name in #29630. Speculation about what might happen in the not-so-near future is all being explored in the Full Site Editing label.

[JustinyAhin]

Thank you for putting together this information @mkaz.

First I would like to suggest that we keep the current name for the developer documentation "Block Editor Handbook".

Full Site Editing is both a project related to the block editor, but is also large enough to have a complete and dedicated documentation outside of the block editor documentation.

So I think it's relevant to have a section for it on Devhub (right next to the block editor section), with all the documentation related to the feature. With of course links to other documentations when needed.