Code reference should have a new sidebar.

[StevenDufresne]

Related to #1.

Instead of using the existing handbook sidebar, we can introduce a newer, better version.

Why

• The handbook code is probably dated (and probably not portable)
• As is, it's not the greatest experience

Screenshot

I haven't included a screenshot because there are plenty of ways to lay it out. I think the main choice would be:

• "within" the context of WordPress.org (with .org header)
• make it appear like its own standalone docs (Ie: Stripe).

[iandunn]

What are the problems that would be better to solve in a new sidebar than by iterating on the existing?

[StevenDufresne]

The source suggested that the handbook sidebar was "clunky, slow, and often confusing"... "I rarely know where to find what I need"

[iandunn]

🤔 I'm having trouble translating that into actionable problems. Compared to the the React docs and Stripe, the fundamentals seem pretty similar.

Similarities:

• hierarchical list
• expand to reveal submenus
• organized into topics

Differences:

• the React docs automatically collapse the previous section when you open a new one. stripe has all sections expanded by default, but lets you collapse if you want.
• react is probably using jamstack or similar. we could probably get similar performance w/ nginx caching etc
• react/stripe have larger fonts
• react has search is in the header, but it looks like it only searches the /docs site; we have a global/network search in the header and a "local" (site) search in the sidebar. stripe also has search in the sidebar.
• react/stripe have fixed sidebars, ours scrolls out of view. personally i like that, but i know it's not the trend.
• we have a Table of Contents aside inside the page content, stripe/react don't
• stripe's entire API docs are one long page, rather than separate pages for each topic.
• react has sidebar on right; we have it on left

Other than the TTFB, I'm not seeing a lot that jumps out as a big win, but I'm sure I'm missing some things.

[iandunn]

I wonder what specific things are confusing, and what's the root cause for them? Maybe it's because we have so many handbooks? To a large extent that feels unavoidable, since WP does so much more than React or Stripe. I'm sure there's some things we could improve though.

I'm also still curious why those problems would be better solved with a new sidebar, rather than iterating on the existing. I'm not against a new one per se, but my default instinct would be to improve it everywhere.

[jonathanbossenger]

often confusing"... "I rarely know where to find what I need"

If I could add my 2c here, I've never felt the sidebar itself was the problem. If we compare it to the sidebars for other documentation projects, the only thing that's always stood out to me is the difference in how the documentation is structured, which is then reflected in the sidebar.

One example I can think of that shows this is in the Block Editor Handbook. I've always felt that the "Getting Started With JavaScript" section should be under the "Getting Started" section, before the Create a Block tutorial, and not in the "How-to Guides".