Gutenberg: Handbook Master Thread

[mtias]

This master thread looks at organizing the work and discussion around the Gutenberg Handbook so we can assign tasks and make progress. I'm going to break down the main areas the handbook should cover.

1) High Level Principles

This covers the mission and vision of the Gutenberg project as it spans across its phases. It frames the effort and informs all the areas of the projects, across developers, designers, and users.

2) Human Interface Guidelines: Design and Dev

These are the principles that govern the approach to building blocks and interfaces for the editor. The main objective is to accurately convey the dos and don'ts to help inform developers and designers about the fundamental aspects of block building towards achieving a consistent and highly usable ecosystem. This also includes UI component documentation and best practices.

3) Code and API Documentation

Currently the bulk of the documents in the handbook are around documenting the code, APIs, and components available. Most of these documents should be synchronized with the source code so that it doesn't grow stale.

4) Resources and References

Showing examples is always a great aid to learning, as imitation is usually the path of least resistance to get started. It also recognizes that the WordPress community is vast and powerful, and that no single resource can be exhaustive enough.

5) Onboarding

This would include more step-by-step tutorials similar to how the "block" section currently reads. It'd help people get started and guide them through the increasing complexity, introducing concepts as needed. It should be complementary to the interface guidelines and the general documentation.

Tasks

Action items are to be tackled in the milestone: https://github.com/WordPress/gutenberg/milestone/50

This is just an initial set of things we should start dividing efforts around.

• [x] Initial work tackling the high level principles was added in #10216 by @alexislloyd and myself.
• [ ] 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.
• [x] Human Interface Guidelines: "the block as the interface".
• [ ] Human Interface Guidelines: "the value of placeholders and guides".
• [ ] Human Interface Guidelines: "components as a means for consistency".
• [ ] Human Interface Guidelines: plan best practices for block building, use examples.
• [ ] Plan out instructions around usage of components.
• [ ] Plan out improvements and structure for Code and API documentation.
• [ ] Plan out "packages" documentation.
• [ ] Start plan for onboarding and tutorials content.

[josephahaden]

Some user-facing pages to add to wordpress.org/gutenberg were suggested on a Trac ticket as well. Paraphrased below.

• A "How to Switch" guide: a non-technical showcase of site(s) with Classic Editor on default going through a testing or transition process. Would include examples of testing, back up, staging, etc. to highlight that switching is safe for most users.
• A "How Gutenberg Handles Older Content" page: an explanation of legacy support and how the "5.0 + Classic Editor plugin" would be the same as "4.9.8 + Gutenberg plugin." Would address upgrade path questions.

[postphotos]

Hi @josephahaden - moving the discussion per your request in Trac Ticket 45073 surrounding documentation, expanding based on this comment.

Here I've quoted and ported the most important part of that ticket, edited here for a little bit of clarity:

There seems to be, quite apparently, a need for _links to why and how_ in a few points in the user flow @jwold and I worked on earlier this week. He's done a great job kept it pretty generic on that ticket already, but there's two additional pages that would be incredibly valuable to users at 5.0 launch,

• A "How to Switch" guide that talks about sites with Classic Editor on default going through a testing or transition process. It wouldn't be too technical; more so an encouragement to test, back up, stage, etc. It'd also highlight that switching is probably safe for many users. I know @danielbachhuber did a ton of work in prepping a technical guide that's spot on and quite informative that we should link to, and there is also the Ramp plugin by VIP already mentioned that makes switching in a slower state much easier. There's probably more someone could write on the subject, too, like trying that "Gutenberg" URL above.

• A "Don't be afraid, Gutenberg doesn't kill your classic" article (that probably has a better title) that explains that Legacy support was a requirement for the tooling of the new editor, and that as of now, the "5.0 + Classic Editor plugin" would be 100% the same as "4.9.8 + Gutenberg plugin." It probably attempts to quell discussions of the need for a fork, an LTS or wearing of a tinfoil hat to keep using WordPress. (None of those are needed.) This upgrade path question is what so many people have been clamoring about, and the project needs to address it straight on.

For both, I'd probably talk about the block conversion tooling of Classic-to-Guten and Guten-to-Classic. So much effort went into solving this problem, and that testing, trying and playing is encouraged.

The goal that @jwold and I have in regard to user flow of activation is to allow sites understand what's going on, how they could respond and what they should probably do next, so that they confidently make the choice to switch at this stage if they've actively chosen not to proceed (via installing Classic.) We feel Gutenberg is worth the effort in playing with and converting to from Classic, it's all about how, when and to what extent on a per site basis.

Also, @gidgey has expressed interest in helping wrangle folks from the Marketing team, if that's helpful. 😄

[postphotos]

And @mtias @josephahaden - the list here looks fantastic, thank you for making progress here! 👍

[chrisvanpatten]

Hi everyone —

As promised in a few places (namely in this week's #core meeting) I've posted over in #core-docs in Slack about kicking off a weekly meeting for Gutenberg handbook work (registration required).

For anyone interested in pitching in on the Gutenberg handbook, please pop over there and comment on the potential meeting times! Thanks :)

[SeanDS]

Suggestion: it'd be nice to get more examples of how to use the sidebar API plugins, like PluginPostStatusInfo. I wanted to add a text control to the sidebar and I searched high and low for a guide on the official WordPress resources, but ended up having to follow this excellent, but unofficial, blog post. It is disappointing how sparse the official documentation is on this front, especially as we are all getting our plugins ready for the imminent release.

[chrisvanpatten]

Great point @SeanDS. We know we have a lot of work to do :)

[nosolosw]

This conversation has helped shape the handbook contents for many iterations. We've just shipped the last one yesterday. We've made a lot of progress in the handbook since. I believe this can be now closed.