search

WordPress / gutenberg

The Block Editor project for WordPress and beyond. Plugin is available from the official repository.
https://wordpress.org/gutenberg/
Other
10.5k stars 4.19k forks source link

Handbook: IA Reorganization #10911

Closed melchoyce closed 5 years ago

melchoyce commented 6 years ago

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
  2. Human Interface Guidelines: Design and Dev
  3. Code and API Documentation
  4. Resources and References
  5. Onboarding

Some questions:

chrisvanpatten commented 6 years ago

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:

mtias commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 (#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 commented 6 years ago

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

youknowriad commented 5 years ago

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

oandregal commented 5 years ago

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.