Handbook: move tutorials and reference docs to the top-level

[oandregal]

Fixes #13962

After multiple iterations by many people, the Gutenberg handbook has a lot of high-quality content 💖 📜 Its biggest issue right now is discoverability. This proposal seeks to improve that while adhering to the current constraints (sidebar only collapsing for the top-level sections, etc.).

In essence, it moves up the tutorials and the reference documentation to the top-level. This would be the TOC and the sidebar:

• Gutenberg Handbook
• Designer & Developer Handbook
• Contributors Guide
• Tutorials
• Block API Reference
• Component Reference
• Data Module Reference
• Filter Reference
• Package Reference

It could be argued that reference docs could be grouped within a "Reference" section. I could agree with that sentiment. However, that approach would suffer from the same problems this PR is trying to fix (long sidebar, lack of discoverability), so I'd rather have them at the top-level.

[gziolo]

What about all the existing url references from blog posts, external projects, search engines, etc.?

[oandregal]

What about all the existing url references from blog posts, external projects, search engines, etc.?

That's a good question. How do we proceed in cases like this? Is it possible to set up redirects?

[gziolo]

@chrisvanpatten should know better as he led the previous handbook structure redesign.

What if we move all auto-generated API docs to their own subfolder instead? I think this would make the menu easier to scan. In particular, I think about:

• https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/
• https://wordpress.org/gutenberg/handbook/designers-developers/developers/components/
• https://wordpress.org/gutenberg/handbook/designers-developers/developers/data/

I also think that tutorials should be one level up:

• https://wordpress.org/gutenberg/handbook/designers-developers/developers/tutorials/ -> https://wordpress.org/gutenberg/handbook/designers-developers/tutorials/

In addition, if we make all sections in the menu collapsed by default, it should make everything way much easier to discover. Actually, if we do it, we can keep API references in the same place :)

[oandregal]

@gziolo My understanding on how the handbook works is that the sidebar only collapses for top-level sections. If that assumption holds true, the only approach I see to fix the sidebar length is to move the longer sections to the top-level (what this PR proposes). Any other approach will suffer from the same lack of discoverability.

Note that I'm not interested in re-architecting the structure of the handbook! I see this proposal as a workaround (that makes sense) to fix the bigger problem we have (improve discoverability).

[gziolo]

My understanding on how the handbook works is that the sidebar only collapses for top-level sections. If that assumption holds true, the only approach I see to fix the sidebar length is to move the longer sections to the top-level (what this PR proposes).

Yes, the sidebar is broken by design :) We should make it possible to collapse subitems for inactive branches rather than play with URL or folder structure. it works perfectly fine for top-level items, so I can't think of any reason why it would be not possible for nested sections.

[mkaz]

Redirects are possible, but I'm not sure how. I see the request occasional made in #meta

This PR overall highlights the biggest issue we have with the documentation, we are publishing into a system we have limited control over, from server config to design.

An even more radical PR approach would be setting up a separate server to publish into, something like Github Pages might be better for documentation. I'm not sure if the goal of getting all documentation into a WordPress instance is all that worthy. This makes it even harder to contribute since users need to be allowed access.

Plus this creates a disconnect, the theme & design are disconnected and not updatable with the documentation. So a contributor who sees an issue with something design, or layout related can't contribute for example the issue we have with the sidebar.

[chrisvanpatten]

Hi all! 👋 I have many things to add!

@gziolo
We should make it possible to collapse subitems for inactive branches rather than play with URL or folder structure. it works perfectly fine for top-level items, so I can't think of any reason why it would be not possible for nested sections.

I agree completely with this, however with the caveat that many folks have tried desperately to find a way to fix the handbook theme, and all have failed.

It would be really helpful if someone with more history/at a higher level in the project (@mtias? @karmatosed?) who knows who originally set up the handbook could point that person to this ticket, so we can talk to them about getting the handbook environment fixed. There are a lot of other UX/UI issues, not just the menu, that could be resolved in the same go.

At this point it's not at all clear who set this up, which Trac repository holds the handbook code (if any?), what the contribution process is, etc.

@mkaz
This PR overall highlights the biggest issue we have with the documentation, we are publishing into a system we have limited control over, from server config to design.

Yes, very much this :)

@nosolosw
How do we proceed in cases like this? Is it possible to set up redirects?

This was a big problem when we did the first reorganization. It also causes problems with moving around the files because the markdown sync plugin isn't always smart about moving pages, and sometimes you can end up with duplicate pages.

@mkaz
An even more radical PR approach would be setting up a separate server to publish into, something like Github Pages might be better for documentation. I'm not sure if the goal of getting all documentation into a WordPress instance is all that worthy. This makes it even harder to contribute since users need to be allowed access.

Ultimately I think this is a really important point, but I want to also toss in the wrench that the awesome WordPress docs team, led by @Kenshino, has done a TON of work setting up DevHub and HelpHub.

I would actually argue an even better solution would be partnering up with @Kenshino, and anyone with available time on the Docs team, to build a totally new importer that can push this content directly into DevHub. Then the Gutenberg handbook site could be completely deprecated and redirected to DevHub.

@danielbachhuber Might also have some context on how WP-CLI's documentation process works (and who helped build it), which I think is the closest analogue to our ideal flow with the Gutenberg documentation.

[chrisvanpatten]

@nosolosw I would check in with @dd32; he helped a bunch the first time we reorganized the docs.

[Kenshino]

Hey all - Jon from the Documentation Team here!

I've discussed with @chrisvanpatten and @0aveRyan a few times about how we should be structuring documentation
I'm not digging in deep about table of contents but really where all documentation (including the block editor) should reside.

The general mandate of us making and maintaining documentation at WordPress.org is to ensure that there is only one specific place for developer documentation - which is DevHub (developer.wordpress.org)

So it's always been assumed and discussed that it would be in e.g. https://developer.wordpress.org/block-editor

We've trained WordPress developers for years to go into DevHub (Codex is actively being deprecated). So we should really capitalise on this trained behaviour.

Beyond where it should reside - I know we're also discussing the technology syndicating it and how it would be maintained.

I'd really like to encourage the Gutenberg team to consider what the WP CLI team did

• Work within the typical handbook CPT
• Copy paste content over
• Work out the technology to syndicate after (they used a modified version of RESTPLAIN to syndicate from GitHub to DevHub)

What should go into DevHub's Handbook are the "How do you develop with Gutenberg" docs. i.e. All the block tutorials you have such as 'Writing your first block type'

What should go into the Code Reference are all the actual source code docs which I believe is going to be resolved with the JS code parser.

You already have a wealth of information here (it's crazy good) - and the key focus here I'd like everyone to look at is

1. Some documentation is better than no documentation
2. Documentation in the right place is more important than the technology that powers it. Discoverability only makes sense if people know where to go to :)

[danielbachhuber]

@danielbachhuber Might also have some context on how WP-CLI's documentation process works (and who helped build it), which I think is the closest analogue to our ideal flow with the Gutenberg documentation.

Are there some specific questions I can help answer?

WP-CLI has a dedicated handbook repository: https://github.com/wp-cli/handbook The markdown files are generated with a series of scripts https://github.com/wp-cli/handbook/tree/master/bin and then imported into make.wordpress.org/cli/handbook.

We avoid the codebase documentation discrepancy issue by only regenerating docs at the time of release. Tutorials, etc. can be updated whenever.

[chrisvanpatten]

@danielbachhuber It's mainly this bit that I'm curious about:

then imported into make.wordpress.org/cli/handbook

A few questions:

• How does that import happen?
• Is the code that runs the import open source somewhere?
• Does someone have to trigger the import, or is it scheduled in some way?
• Who wrote the code that runs the import, and who currently "owns" it?
• Are there any issues with the workflow that you've encountered?

Thanks 🙌

[danielbachhuber]

• How does that import happen?
• Is the code that runs the import open source somewhere?

Using some code here: https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/plugins/wporg-cli/inc/class-markdown-import.php

In fact, the existing Gutenberg handbook uses a derivative of this!

• Does someone have to trigger the import, or is it scheduled in some way?

WP Cron for lyfe!

• Who wrote the code that runs the import, and who currently "owns" it?

I wrote it. Everyone owns the copyright!

• Are there any issues with the workflow that you've encountered?

Seems to work reasonably well, although @schlessera might have opinions about it.

Personally, I much prefer to have the codebase documentation updated at release time, over being continuously updated. I think it's a reasonable expectation the published documentation correlates with the latest stable release.

[oandregal]

This is what @dd32 taught me about redirects:

• The code for the redirects lives here.
• It is possible to set up manual redirects (see code above).
• If the slug of the page (last bit in /this/is/the/SLUG/) remains the same it'll be redirected automatically.

The changes introduced in this PR shorten the page URL removing the designers-developers/developers part, so my understanding is that they'll be redirected automatically:

Section	Before	After
Tutorials (+33 subsections)	https://wordpress.org/gutenberg/handbook/designers-developers/developers/tutorials/	https://wordpress.org/gutenberg/handbook/tutorials/
Block API (+6 subsections)	https://wordpress.org/gutenberg/handbook/designers-developers/developers/block-api/	https://wordpress.org/gutenberg/handbook/block-api/
Components (+65 subsections)	https://wordpress.org/gutenberg/handbook/designers-developers/developers/components/	https://wordpress.org/gutenberg/handbook/components/
Data (+9 subsections)	https://wordpress.org/gutenberg/handbook/designers-developers/developers/data/	https://wordpress.org/gutenberg/handbook/data/
Filters (+4 subsections)	https://wordpress.org/gutenberg/handbook/designers-developers/developers/filters/	https://wordpress.org/gutenberg/handbook/filters/
Packages (+19 subsections)	https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/	https://wordpress.org/gutenberg/handbook/packages/

[oandregal]

Got confirmation from Dion that this holds true. If any particular section fails to redirect we can fix it in a case by case basis. We don't expect any to fail, though, and I've tested that the proposed changes are already redirected.

[oandregal]

This is where things stand for this PR:

• The changes here are ready. There is wide agreement that this fixes our current handbook for users, which is a frustrating experience as it stands. There is also interest in bigger changes that I'd like to tackle independently so we're not blocked to improve what we currently have.

• The old URLs will be automatically redirected to the new ones. If a particular section fails to do this, we can add the manual redirect after. I'll follow up on this.

All things considered, I'm prepared to merge this in as soon as someone gives me a 👍 Would like to time the merge to make sure someone from meta is around.

[oandregal]

Relevant Slack thread.

[oandregal]

Closing this in favor of https://meta.trac.wordpress.org/ticket/4388