Improve the table of content of the block editor developer handbook

[JustinyAhin]

Description

The next step after improving the homepage of the block editor handbook (#28142) will be to also improve the current table of content. Right now, the table of content is managed in this JSON file https://github.com/WordPress/gutenberg/blob/master/docs/toc.json.

The goal for this step is to give the TOC a more coherent structure by, for instance, grouping chapters that would make sense being together, adding content that are not yet present in the documentation.

Ideas or proposals for improving to improve the TOC are welcome under this issue.

[paaljoachim]

https://developer.wordpress.org/block-editor/

Here is an overview in addition to the link Justin mentioned above:
Getting started
-Glossary
-FAQ
-Versions in WordPress
-History
-Outreach

Architecture
-Key Concepts
-Data Flow and Data Format
-Folder Structure
-Modularity
-Performance
-Automated Testing
-Fsetemplates (Could instead be FSE templates or Full Site Editing Templates)

Developer Documentation
-Block API Reference
-Filter Reference
-SlotFills Reference
-RichText Reference
-Internationalization
-Accessibility
-Feature Flags
-Theming for the Block Editor
-Backward Compatibility
-Gutenberg as a Development Platform (Could instead be: Development Platform)

Designer Documentation
-Block Design
-User Interface
-Resources
-Animation

Contributor Guide
-Code Contributions
-Design Contributions
-Documentation Contributions
-Triage
-Localizing Gutenberg Plugin
-Repository Management

Tutorials
-Development Environment
-Getting Started with JavaScript
-Create a Block tutorial
-Blocks
-Meta Boxes
-Displaying Notices from your Plugin or Theme (Could instead be: Displaying Notices)
-Creating a Sidebar for Your Plugin (Could instead be: Creating a Sidebar)
-Introduction to the Format API (Could instead be: The Format API)
-Creating a block-based theme (Could instead be: Creating a theme)

Component Reference
->

Data Module Reference
->

Package Reference
->

Btw this should also give us some ideas on additional tutorials etc that would be nice to get added into the documentation.

[annezazu]

Thanks for kicking this off! Just noting two things:

• I didn't know where else to put the Versions in WordPress doc and don't care where that's placed. It feels like an "odd man out" in many ways and didn't fit nicely in any of the headings.
• The FAQ is fairly up to date as I did a revamp of that a few months back so we can feel more confident having that as an early starting point.

Btw this should also give us some ideas on additional tutorials etc that would be nice to get added into the documentation.

Agreed! This reminds me that previously someone (can't remember who) mentioned it would be neat to have "first steps" added to the core handbook but the same idea might be neat to have here too:

https://make.wordpress.org/design/handbook/get-involved/first-steps/

Noting to myself that the Outreach page is woefully out of date... might try to work on updating that while this overhaul is done :)

[JustinyAhin]

@paaljoachim I have a first proposal for the toc.
It is not complete yet, so it can be edited again. Here is what it looks like

### Developer Documentation
- Installation
	- Development environment
- Getting started
- Develop for the block editor
	- Architecture
		- Key Concepts  
		- Data Flow and Data Format  
		- Folder Structure  
		- Modularity  
		- Performance  
		- Automated Testing  
	- FSE <!-- We are yet to decide where FSE docs should be -->
	- Block Style Variations
	- Creating Block Patterns
	- Theming for the Block Editor
	- Block API Reference
	- Block Editor Accessibility
	- Internationalization
- Tutorials
- Appendix
	- Component Reference
	- Data Module Reference
	- Package Reference
	- Backward Compatibility
	- Gutenberg as a Development Platform
	- Glossary
	- Frequently Asked Questions
	- Versions in WordPress
	- History

### Contributor Guide
 - Code Contributions 
 - Design Contributions 
 - Documentation Contributions
 - Triage 
 - Localizing Gutenberg Plugin 
 - Repository Management

### Designer Documentation

What I've tried to do first is to regroup everything that is related to developing the block editor of for the block editor inside the developer documentation chapter. I also followed inside this chapter the structure that is on the homepage.
Finally, I created an Appendix subchapter to add stuff like glossary, the different references (package, component, data module).

[paaljoachim]

That looks really good, Justin!

I went back and forth compared to the current Block Editor handbook.
The new Table of Contents looks nicely organized. I do agree that developer focused sections should be regrouped within the Developer Documentation. It feels like it is the most logical place to add them.

I would switch these sections:

• Installation
  • Development environment
• Getting started

To:

• Getting started
• Installation
  • Development environment

Beginning with the Getting started page. After that it feels natural to have the Installation guide.

Let's get Marcus @mkaz to also take a look and give feedback.

[mkaz]

I think you could include Installation and Development Environment under Getting Started.

I would group allt the API reference documentation together, maybe as a sub-section under Develop

I'm not sure Architecture is needed in Develop for the Block Editor, it is more core to the Gutenberg project, not needed to extend the editor. @youknowriad might have some thoughts on where it could go, he organized that section.

Also, the "Develop for the Block Editor" is in the Developer Documentation category, I'm not sure there is a clear distinction for the added level.

I think overall grouping into sections by how people coming in are thinking, maybe styles, blocks, themes, or something along those lines. Also, before implementing I think we need to figure how Full Site Editing fits in, so any re-org only needs to happen once. There is a bit of work with how publishing from GitHub to site is done, especially if moving and renaming things.

@annezazu might have some thoughts for FSE parts, so tagging her.

[youknowriad]

Thanks for the proposal @JustinyAhin I share some of the opinions expressed above:

• I assume the home page stay as is
• Getting started being the first thing after the home page
• Architecture don't belong in "develop for the block editor". It's more for contributors and folks that want to go into the details. Maybe it deserves to stay as its own section?
• I'm not sure I like the fact that the "development environment" being too high in the list. I think maybe we should just hint and link to it in "Getting started" but leave it in "Tutorials" or something like that. Actually, ideally it should be part of the "plugins handbook" since it's common to all plugins but I guess it's not possible because of how we deploy the docs.
• Appendix looks like a folder to put anything that is hard to organize properly, maybe it's fine as a start.
• With this new organization maybe design documentation should move to other sections like "contributor"...
• It seems there's a number of other pages in the current handbook that are missing from this proposal (Slot fill, RichText...)
• "Gutenberg as a Development Platform" this is more a tutorial I think

The other thing here is that are docs in the handbook that are not specific to the block editor and maybe in the future we want to find a better way to deploy them in the WordPress docs even if they are maintained in this repo:

• Components reference: This is not specific to the block editor, anyone can use thse
• Data Module Refereence: There are stores that are specific to the block editor but not all of them
• Package Reference: Most npm packages are not specific to the block editor
• Internationalization: Helpful for any plugin

[annezazu]

Thanks so much for all the work and effort that's gone into this. I'll add some additional thoughts:

• I do think Architecture should be a separate section and still included somewhere but perhaps less prominently (not as close to the top) as I think it could lead to a quick sense of feeling overwhelmed. People do ask about the architecture of the block editor and it feels important to share that knowledge with more people.
• I have a feeling FSE items will exist both in Develop for the block editor and in the Tutorials section. As long as we're okay with that, I think what you shared above makes sense. I feel strongly that it should be higher up on the list as it's obviously an important topic!
• I don't feel super strongly about this but I do think having the Frequently Asked Questions under Getting Started would be smart.

[JustinyAhin]

Thank you for all the feedbacks Paal, Marcus, Riad and Anne. I'm working on integrating them and will post a new version of the toc here tomorrow.

[JustinyAhin]

* With this new organization maybe  design documentation should move to other sections like "contributor"

@youknowriad I don't understand why design documentation should move under "Contributor" section (is it what you are suggesting?).

From what I'm reading on the design page, "this documentation will provide resources for creating beautiful and intuitive layouts."

[JustinyAhin]

Here's the structure that is more complete and improved using your suggestions

https://gist.github.com/7084adee8abca28c8da8652ebbb1da6f

[JustinyAhin]

I have a couple of new readme files to write, before sending a draft PR

[paaljoachim]

It looks really good, Justin!
Are you planning having readme's that give an introduction to the various sections? (kinda like the Block editor intro page)
As it would be nice with an overview before digging into the contents of a specific section.

[JustinyAhin]

@paaljoachim as I've created a new folder for appendix, I want to create a readme for this folder with the list of links to file that are in it.

[annezazu]

Thanks for the updated version! My only follow up feedback is how far down in the table of contents things like the history of the project and the FAQ are. I'm of two minds about this: perhaps it's been long enough now that an intro is not needed VS it's always important to clearly state/show the value add the core editor brings.

[DaisyOlsen]

I have a couple of opinions to share 😁

The first level items seem out of order to me.

I would rather see:

• Developers
• Designers
• Contributors
• Architecture
• Appendix

I think it flows better to have the three types of people likely to benefit from this information at the top followed by resource materials.

I also agree with @annezazu that FAQ and History should more prominent. Is there a strong feeling that the "Getting Started" section is not valuable? As it stands all the links that are currently in the TOC under the Getting Started Item are moved into Appendix which will leave no sub-items there. I'd recommend to move FAQ and History back up into that space, knowing that the content of the pages will be updated in a later phase of this project.

[mkaz]

If we are going to be doing a massive re-organization of all the docs, then I would like to see us remove the "By Role" aspect of the documentation and move to a "By Function" org structure. For example, what does a person creating a theme consider themselves? A developer? A designer? Both, right?

So moving things to a functional nature of:

• Using the Block Editor,
• Extending the Block Editor, and
• Contributing to the Block Editor

Also, I think we need to consider the overall UX and flows before we start re-arranging all of the files. I think we need to consider the overall documentation as a system and how it all fits together. So look at people with specific goals:

• I want to create a theme, how do I do that now?
• I want to create a block?
• I want to contribute to Gutenberg?
• How do I use the data store?
• How do I learn more about JavaScript and WordPress?
• ...

This is a good read about Documentation Systems, there are many different types of docs that we should consider how they all fit together.

[DaisyOlsen]

This is a good read about Documentation Systems, there are many different types of docs that we should consider how they all fit together.

This looks like an excellent resource, thank you for sharing @mkaz

I agree with what you've said about moving to a funtional structure rather than relying on readers to self-identify as a specific role, hoping to find the right resources for their needs.

[mtias]

Agreed with @mkaz with the clarification that the user handbook has already split the "how to use the block editor" in https://wordpress.org/support/article/adding-a-new-block/

So the block editor handbook should be for understanding the key concepts around blocks; extending the block editor through new blocks, plugins and themes; using the gutenberg tools for other projects (components, packages, etc); and finally contributing to the Gutenberg core.

I'd like to rephrase the "getting started" into "Introduction" and I think we should move "key concepts" there instead of having it within "architecture".

I also think most of the stuff in "getting started" is more "reference" material that is not that important to know initially.

[JustinyAhin]

Thank you for sharing the link about documentation system @mkaz. It's a very good read.

Here's what I came up with for the structure based on that:

• The current documentation have pages that serves the four purposes: tutorial, how-to guides, reference guides and background information
• The current Tutorials section (https://developer.wordpress.org/block-editor/tutorials/) can stay as in, and this tutorial is added to it (https://developer.wordpress.org/block-editor/developers/platform/custom-block-editor/)
• What is currently in the Developer Documentation + Designer Documentation can be assimilated to How-to guides
  • We will maybe need to group them by specific goals (themes, plugins, extending the block editor)
• Component Reference, Data Module Reference and Package Reference can go under References guides
• As Contributor Guide doesn't fit in any of the four purposes I mentioned above, it can stay as a section apart.

So, we'll have the doc structured as:

.
├── Getting Started/
│   └── Tutorials
├── How-to guides
├── Reference guides
├── Background information
└── Contributor guide

The names are inspired by the documentation system post, but they can be changed/adapted obviously.

I summarized all this in this gist: https://gist.github.com/8f6fc4b7b4252bd5c6d9d7baa7e015af

[DaisyOlsen]

@JustinyAhin Where do the How-to guides come from in this structure? Do they differ from Tutorials? If so I'd love to be sure I understand the distinction!

[JustinyAhin]

@DaisyOlsen the How-to guides contains pages from the Developer Documentation + Designer Documentation chapters.

.
└── How-to guides/
    ├── Block API Reference/
    │   ├── Block Registration
    │   ├── Edit and Save
    │   ├── Attributes
    │   ├── Block Context
    │   ├── Deprecated Blocks
    │   ├── Block Supports
    │   ├── Block Transforms
    │   ├── Templates
    │   ├── Block Type Metadata
    │   ├── Block Patterns
    │   ├── Annotations
    │   └── Block API Versions
    ├── Filter Reference/
    │   ├── Block Filters
    │   ├── Editor Filters (Experimental)
    │   ├── Parser Filters
    │   └── Autocomplete
    ├── SlotFills Reference/
    │   ├── MainDashboardButton
    │   ├── PluginBlockSettingsMenuItem
    │   ├── PluginDocumentSettingPanel
    │   ├── PluginMoreMenuItem
    │   ├── PluginPostPublishPanel
    │   ├── PluginPostStatusInfo
    │   ├── PluginPrePublishPanel
    │   ├── PluginSidebar
    │   └── PluginSidebarMoreMenuItem
    ├── RichText Reference
    ├── Feature Flags
    ├── Theming for the Block Editor/
    │   ├── Theme Support
    │   └── Themes & Block Editor: experimental theme.json
    ├── Backward Compatibility/
    │   ├── Deprecations
    │   └── Meta Boxes
    ├── Gutenberg as a Development Platform
    └── Designer Documentation/
        ├── Block Design
        ├── User Interface
        ├── Resources
        └── Animation

[DaisyOlsen]

Ah I see. I'm not sure that "how to guides" is the right label for this but I don't have an immediate alternative.

@priethor - Were you thinking about documentation organization? Does this conversation weigh into that process at all?

[priethor]

Ah I see. I'm not sure that "how to guides" is the right label for this but I don't have an immediate alternative.

I agree with @DaisyOlsen on this, according to the Documentation Systems read suggested by @mkaz "How to guides" are problem-oriented; I believe "Block API Reference, "Filter Reference", etc. should be under "Reference guides", as apart from having "reference" word in their name, they are information-oriented rather than problem-oriented.

On the other hand, I would suggest most of the "Tutorials" currently in the block editor handbook would be better classified as Howtos. For example, "Loading JavaScript" or "Displaying notices" each solve a particular problem, independent from one another.

[JustinyAhin]

Thanks for the feedback Daisy, Héctor. I'll share another proposal soon

[JustinyAhin]

@priethor I did a bit of reorganization (https://gist.github.com/8f6fc4b7b4252bd5c6d9d7baa7e015af).

What it looks like now:

• The "Block API Reference, "Filter Reference", "Slotfills Reference" are moved under the Reference guides chapter
• As you said, it makes sense that topics under tutorial that are not "learning oriented" or won't be understood by a beginner with the block editor are moved under the Howtos section

[priethor]

Thanks for your effort @JustinyAhin , I believe the structure is much more comprehensive now 🎉

The only other improvement I would suggest would be regarding the "Architecture" section: I think it should live under "Getting started / introduction", since the high-level architecture description and key concepts are the first material to be checked when getting started, along with the glossary. On the other hand, the "Versions in WordPress" and "Folder Structure" don't fit, in my opinion, a "Getting Started" section, they feel more like contributor material (e.g., extenders don't need to know how the Git repository is organized).

I would definitely love to hear some more thoughts in this regard, though. 🙂

[JustinyAhin]

Thanks for the feedback
Adding the changes to the PR