Block Author Focused Documentation in Storybook

[epiqueras]

Currently, prospective block authors don't have a canonical, focused source of documentation for them to get started building custom blocks.

The Block Editor Handbook is very hard to navigate and contains information on all aspects of Gutenberg, most of which are irrelevant to block authoring.

I think that the barrier to entry to authoring blocks is way lower than our documentation makes it out to be and that having focused documentation for this would also serve as an onramp for potential future Gutenberg contributors.

Our new Storybook MDX powered docs pages would make a great home for this new documentation.

I suggest we restructure the storybook into the following sections:

• Playground
• Docs
  • Getting Started (Setting up an environment and all that.)
• Recipes
  • Basic Block Plugin
  • Block Style Variations
• Advanced Guides
  • Deprecating Block Versions
• Components (Include "Other")
• Blocks API Reference
• FAQ

We should also theme our storybook to better fit the WordPress brand.

[epiqueras]

cc @ItsJonQ @aduth

[youknowriad]

I wouldn't suggest starting to document a lot of things in Storybook yet unless we figure out how to put things in wp.org first. We can't start by reorganizing the handbook if needed.

[epiqueras]

Storybook outputs static markup so that shouldn't be hard.

[mkaz]

I agree the Block Editor Handbook could use some improvements. It contains a mix of interests and is not necessarily clear about the intent of all its pieces of documentation. I found this article about the Four Types of Documentation useful when thinking about our documentation. The four types being Tutorials, HowTos, Explanations, and Reference.

The other aspect mixed into our Gutenberg docs is the audience, we have developers, designers, contributors, and users. These audiences are mixed together both as developers of Blocks and contributors to the Gutenberg project. Also, I'm not sure it makes sense to still make a split between developers and designers.

I don't have a structured proposal yet on what our docs should look like, but agree with @youknowriad that we should probably iterate on current docs reorganization. I would like to think about a structure that takes into account audience first, and then the type of documentation needed for that audience.

I see StoryBook being a great resource that fills the API Reference probably for multiple audiences.

Thoughts?

[oandregal]

I also agree we should focus on iterating on contents within the handbook (reorganizing, updating, creating as necessary) and fill gaps as necessary.

One gap that a Storybook-like tool can fill is showing components live pair with its code. I'd love to have that. What would we need to do to take Storybook (or its components, or something similar) and embed it into the handbook?

[epiqueras]

It's a static app, we could even just iframe it.