Handbook: IA Reorganization

[melchoyce]

This issue goes more in-depth into the Handbook IA, as mentioned in #10549:

Rework the IA (information architecture) and navigation of the handbook to better cover the main areas outlined above. As it stands, it's incredibly confusing to navigate and has a lot of overlap between sections.

I've been taking a look at how we can reorganize the existing Handbook content into the five new categories (High Level Principles, Human Interface Guidelines: Design and Dev, Code and API Documentation, Resources and References, Onboarding).

---

1. High Level Principles
   • Introduction
   • Principles
   • Design Principles
2. Human Interface Guidelines: Design and Dev
   • The Language of Gutenberg
   • The Block as the Interface
     • Patterns
   • The Value of Placeholders and Guides
     • Content should be grabbed from existing pages, since this information is currently interspersed between a lot of sections.
       1. The Language of Gutenberg
       2. Block Design Best Practices
   • Components as a Means for Consistency
     • We’ll be able to grab some of this content from existing pages, but will likely have to write most of it from scratch.
     • Would be good to also expand on accessibility here.
   • Plan best practices for block building, use examples
     • Block Design Best Practices
   • Best practices for extending Gutenberg outside of blocks
     • Registering extra sidebars
     • Meta boxes
     • etc.
3. Code and API Documentation
   • The Block API
     • The Gutenberg block grammar
     • Attributes
     • Edit and Save
     • RichText API
     • Deprecated Blocks
   • Templates
   • Components
   • Extensibility
     • Extending Blocks
     • Extending Editor
     • Meta Boxes
     • Theme Support
   • Packages
     • Package List
     • Data Package
4. Resources and References
   • General
     • History
     • Glossary
     • FAQs
     • Release Process
     • Repository Management
     • Deprecated Features
   • Design Resources
   • Coding Resources
     • Coding Guidelines
     • Testing Overview
     • Scripts
   • Outreach
     • Articles
     • Meetups
     • Talks
     • Resources
5. Onboarding
   • Creating Block Types

---

Some questions:

• Does this organization make sense?
• Can we break up these categories into further sub-categories?
• Am I missing any pages?

[chrisvanpatten]

I'd love to see some documentation for post type templates and theme support moved out into "Onboarding" and see Onboarding get three sub-sections for Users, Themes, and Plugins.

This would basically serve as "If you're in Group X, here's what you need to know about Gutenberg".

The revised section would also include the "How to switch" and "How to not switch (aka Classic Editor)" documentation based on the suggestions over here.

One proposed structure:

• Onboarding/Getting Started
  • What to do before updating to 5.0 (aka backup, test in a staging site if you can)
  • How to keep the Classic Editor experience (Classic editor plugin)
  • Themes (Docs: Section specifically for theme authors #10764)
    • Theme support options
    • Post type templates
    • Block markup and CSS classes to target
  • Plugins
    • Notes on meta box compatibility
    • Links to—or a simplification/merged version of—@danielbachhuber's documentation on hooks/functionality that are deprecated or replaced in g7g
  • Users
    • Meet the new editor UI
    • Basic FAQ/"How do I do X" section

[mtias]

Thanks @melchoyce this is great start.

I prefer "Getting Started" to "Onboarding" as a term. I also think "Getting Started" could potentially be placed under the HIG.

@chrisvanpatten I don't think we should move the documentation per se as people wanting to find out about theme support APIs should still be able to find it there without having to go through the "onboarding/getting started" section.

cc @pento how should we handle URL updates in the case of invalidating permalinks?

[mtias]

The other point to consider is how we call these top level sections from a navigation perspective, as they might not be clear enough on their own. "High Level Principles" could be just "Vision" for example.

[ajitbohra]

Question:
How do we plan to position onboarding section, as a quick info on block creation or as a tutorial/guide to create & extend blocks?

Suggestion:
Adding a Getting Started section to get up and running with the required environment for block/plugin development. As many folks referring to this might feel lost if they are not familiar with JS World.

We can adopt https://github.com/youknowriad/wp-js-plugin-starter here :)

[DrewAPicture]

Hi 👋🏻

Handbook IA

Looking at the proposed IA here, I think it begs a mention that care should be taken not to glom all things Gutenberg into one handbook for the sake of it. As a long time maintainer for DevHub and former docs team lead, I can tell you that keeping the responsibilities of user-facing handbooks simple is a must, if only to avoid future confusion and a rising maintenance burden.

For instance, I note that you have a Resources and References section in what is otherwise by all accounts a user-facing handbook. This information is absolutely useful ... to the Gutenberg team and its contributors. As per the organizational style of the Make network on .org, each Make community has their own contributor-facing handbook. That is where the bulk of this contributor-facing information should live.

Any Gutenberg development information specific to WordPress should live either in the Plugin and/or Theme Development handbooks on DevHub or as a standalone Gutenberg handbook, again, on DevHub. Hopefully that makes sense.

"Official" Docs Reflect Latest Stable

On another note, I don't see it mentioned but it's worth clarifying that any docs coming from parsed source should reflect only current stable code. This is a policy we follow on DevHub for core as well as in the Theme and Plugin Development handbooks.

[chrisvanpatten]

I think there is some value to keeping Gutenberg documentation centralised for at least the short term, while it's so new and since the contribution process is fairly different than the rest of core.

That said it could certainly make sense to split more cleanly into "Developing Gutenberg" and "Using Gutenberg" handbooks, but one of the challenges is that there's a degree of overlap, especially for developers. The packages and components documentation is relevant both to people developing Gutenberg and people developing for Gutenberg, and are one of the biggest documentation areas.

I can't speak on behalf of the leads but I don't think there's necessarily any opposition to putting the Gutenberg handbook into DevHub but I know from a practical perspective we would need to sort out a way to differentiate documentation for the version of Gutenberg in core, vs the version that lives on in the plugin. Does DevHub make it possible to build and switch between multiple versions of documentation, or would that mean basically maintaining two handbooks in parallel?

Happy to discuss this further in today's #core-docs meeting at 2pm ET. I'm pretty flexible on what the final implementation looks like (and truthfully I'm not sure I have the authority to make a decision anyway) but as we start divvying up the work it would be great to settle on a definitive "this is how we're going to do it".

[danielbachhuber]

I know from a practical perspective we would need to sort out a way to differentiate documentation for the version of Gutenberg in core, vs the version that lives on in the plugin. Does DevHub make it possible to build and switch between multiple versions of documentation, or would that mean basically maintaining two handbooks in parallel?

If we're keeping the Markdown -> WordPress workflow, then we can have two separate manifest.json files, one feeding DevHub and the other feeding the Make Handbook.

[chrisvanpatten]

Based on some of the feedback, here's a new proposed outline. I didn't go into as much detail in some sections (e.g. the HIG) but that would all be there still.

https://www.notion.so/chrisvanpatten/IA-Outline-ec2bc7d6348f43dca23cae127f605c7b

Would love thoughts @melchoyce @mtias :)

EDIT: Pasting it in for posterity:

1. Building Gutenberg
   1. Introduction
   2. Philosophy
   3. Design
      1. Design Resources
      2. Link to HIG
   4. Develop
      1. Coding guidelines
      2. Testing
      3. Release Process
      4. Deprecations
      5. Links to components/package references
   5. General
      1. History
      2. Glossary
      3. FAQs
      4. Repository management guidelines
2. Using the new Editor
   1. Users
      1. Meet the new Editor (high level UI overview)
      2. Sticking with Classic
      3. How do I… (common FAQ)
   2. Building blocks and plugins
      1. Tutorials
         1. Build your first block
         2. Build your first plugin sidebar
         3. Extend a block
         4. Extend the editor
      2. Developer Reference
         1. Blocks API
         2. Plugins API
         3. Components
         4. Registered scripts
         5. Block filters
         6. Editor filters & slotfills
      3. Designer Reference
         1. Human Interface Guidelines
         2. Preparing block icons
   3. Theming for the new editor
      1. Theme support list
      2. Block HTML & CSS reference (classes to target)
      3. Editor styles
      4. Block style variations
   4. Backwards compatibility
      1. Meta boxes
      2. Important deprecations/changes from 4.x
   5. Resources
      1. Articles
      2. Meetups
      3. Talks

[chrisvanpatten]

Hi everyone —

Based on our discussion yesterday, we are going to try to split our written documentation into three handbooks:

1. Contributor Handbook (building Gutenberg)
2. User Handbook (how to publish posts, etc.)
3. Designer & Developer Handbook (how to build blocks, design themes, etc.)

With that in mind, I reorganised the IA outline again. Here's how I see it getting split up:

1. Contributor Handbook
   1. Introduction
   2. Philosophy
   3. Design
      1. Design Resources
      2. Link to HIG
   4. Develop
      1. Coding guidelines
      2. Testing
      3. Release Process
      4. Deprecations
      5. Links to components/package references
   5. General
      1. History
      2. Glossary
      3. FAQs
      4. Repository management guidelines
2. User Handbook
   1. Meet the new Editor (high level UI overview)
      1. Manual for users of assistive technologies (Manual for users of assistive technology #10373)
   2. Sticking with Classic
   3. How do I… (common FAQ)
3. Designer & Developer Handbook
   1. Building blocks and plugins
      1. Tutorials
         1. Build your first block
         2. Build your first plugin sidebar
         3. Extend a block
         4. Extend the editor
      2. Developer Reference
         1. Blocks API
         2. Plugins API
         3. Components
         4. Registered scripts
         5. Block filters
         6. Editor filters & slotfills
      3. Designer Reference
         1. Human Interface Guidelines
         2. Preparing block icons
   2. Theming for the new editor
      1. Theme support list
      2. Block HTML & CSS reference (classes to target)
      3. Editor styles
      4. Block style variations
   3. Backwards compatibility
      1. Meta boxes
      2. Important deprecations/changes from 4.x
   4. Resources
      1. Articles
      2. Meetups
      3. Talks

For the time, these handbooks should continue to be built from this GitHub repo. This also gives us some extra flexibility because we should be able to have multiple targets: e.g. we build these three handbooks separately, but then also build a combined handbook for the plugin version of Gutenberg.

I'm looking to finalise this by tomorrow at 12pm ET, so please comment with feedback. This is not going to be a locked/unchangeable document but it should be good at a high level :)

[chrisvanpatten]

(Note: I'd like suggestions on the User Handbook in particular.)

[youknowriad]

@chrisvanpatten Is this issue still relevant, I feel that the reorganization happened already?

[oandregal]

These conversations have been instrumental through the many docs iterations. We've just shipped the last iteration (can be seen at https://developer.wordpress.org/block-editor/) and the state of docs is now different than it was months ago. I believe we can close this.