Add description for Reusable Blocks

[0aveRyan]

Addresses #8345

Description

Add description guidance for Reusable Blocks.

Screenshots

Types of changes

• In-app documentation

[ZebulanStanphill]

Perhaps "change sync" should be "changes apply to all instances" or something like that? But anyway, this is definitely a big improvement over having no description. I like the mention of the Convert to Regular Block option to let the user know that Resuable Blocks can also be used as templates.

[0aveRyan]

@ZebulanStanphill Definitely open to wordsmithing this! However instance is a development concept and I think confusing to an everyday user.

I'd played with content and formatting changes sync, changes will reflect and Use again and again.

I'd like to see Convert to Regular Block formatted somehow (or perhaps make a functional link?)... but try to avoid formatting in translatable strings.

Separate issue, but the Reusable Block Name textbox and getting Convert to Regular Block into the sidebar would help un-bury these functions.

[chrisvanpatten]

Suggestion:

This is a reusable block, which can be shared between multiple pages and posts. When edited, the block will automatically update wherever you have it inserted.

[ZebulanStanphill]

@chrisvanpatten Nice! I do wish that Convert to Regular Block was mentioned, but that is mainly because that option is not as discoverable as I would prefer.

Separate issue, but the Reusable Block Name textbox and getting Convert to Regular Block into the sidebar would help un-bury these functions.

Related: #8403

[chrisvanpatten]

I do wish that Convert to Regular Block was mentioned, but that is mainly because that option is not as discoverable as I would prefer.

I considered that, but ultimately I don't think it's really appropriate to treat the descriptions as help docs — it gets unwieldy very quickly. Perhaps that could be explained in a dot tip?

[ZebulanStanphill]

@chrisvanpatten A dot tip would help, but I think using Reusable Blocks as templates should become less of a second-class ability. Currently, I do not really use Reusable Blocks for their global instance ability. I only use them for inserting templates like placeholder text that I can then quickly modify. As proposed in #8403, you should be able to choose whether to insert a Reusable Block as a global instance or a template when you insert it, similar to what Oxygen does with its Reusable Parts.

[chrisvanpatten]

As proposed in #8403, you should be able to choose whether to insert a Reusable Block as a global instance or a template when you insert it, similar to what Oxygen does with its Reusable Parts.

I think better to solve that problem over in #8403, rather than in this PR then :)

[ZebulanStanphill]

@chrisvanpatten Agreed. I'm happy with your proposed description.

[0aveRyan]

@chrisvanpatten @ZebulanStanphill took a second pass aiming at more brevity.

Recommendation is a bit long, visually

• The description is right below the "Reusable Block" title, so truncated beginning.
• Remove you
• Remove reference to page & post as these could be used on Products, Movies, etc

[ZebulanStanphill]

I think it could be even simpler:

When updated, changes apply everywhere this Block is inserted.

Also, should "block" be capitalized here or not?

[0aveRyan]

[michelleweber]

I like the evolution here. I might want to add a few words to be super clear that you can use the block anywhere, not just on the post/page where you create it, and to be a little more active. Maybe something like

Create content, and save it to add to any post or page. Update the block, and the changes apply everywhere it appears.

[chrisvanpatten]

I love that latest revision @michelleweber!

[michelleweber]

Woot :)

[ZebulanStanphill]

@michelleweber I like your iteration, but I think it should be modified to avoid referencing posts/pages specifically since Reusable Blocks can (of course) be used in custom post types, as well as the future use of blocks in sidebars, footers, headers, and etc. What do you think of this:

"Create content, and save it to reuse across your website. Update the block, and the changes apply everywhere it appears."

[0aveRyan]

Updated to reflect sitewide use and swap appears for used because it's a reusable block.
Create content, and save it to reuse across your site. Update the block, and the changes apply everywhere it's used.

[ZebulanStanphill]

@0aveRyan You should use ’ instead of '. The former is a fancy apostrophe that does not conflict with the typewriter apostrophe and single quotation mark character. That allows you to avoid having to escape the apostrophe, and also being slightly nicer semantically. (It is also recommended to use the direction-specific quotation marks for quotations for the same reason.) The fancy quotation marks are already used in the dot tips:

Welcome to the wonderful world of blocks! Click the “+” (“Add block”) button to add a new block. There are blocks available for all kind of content: you can insert text, headings, images, lists, and lots more!

You’ll find more settings for your page and blocks in the sidebar. Click ‘Settings’ to open it.

If you look closely (and depending on how different they look in your font), you will notice that the fancy quotation marks are used there instead of the neutral ones.

(Actually, I just noticed that the dot tips are inconsistently using double quotation marks vs single quotation marks. I have opened an issue for that: #9205.)

See also:
https://en.wikipedia.org/wiki/Apostrophe
https://en.wikipedia.org/wiki/Quotation_mark

[michelleweber]

A question: do we think most users make a distinction between "post" and "custom post type"? They're all posts. I've seen this issue crop up in a few places, and I just want to pause to consider it's usefulness for basic instructions and descriptions. I tend to think "post" covers it in cases like this, but I'd like to know if/why I'm wrong so I can avoid similar confusion in the future.

[chrisvanpatten]

A question: do we think most users make a distinction between "post" and "custom post type"? They're all posts. I've seen this issue crop up in a few places, and I just want to pause to consider it's usefulness for basic instructions and descriptions. I tend to think "post" covers it in cases like this, but I'd like to know if/why I'm wrong so I can avoid similar confusion in the future.

I have experienced users who don't understand that "post" also includes "pages" but the confusion doesn't typically extend beyond that. (The term "custom post type" itself is definitely confusing, but I don't think it's used anywhere in Gutenberg anyway.)

[0aveRyan]

@michelleweber @chrisvanpatten I agree the nuance of the distinction isn't deeply important to some users, but avoiding reference to Posts and Pages I think gives these blocks more resiliency for use in WooCommerce, other e-commerce contexts, media publishing and yet-to-be-invented formats 10 years from now.

In news and media publishing, organizations often customize WP with highly specific nomenclature for posts (stories, blogs, longform, slideshows, investigations, projects) there are functions for it in themes like Largo Project.

Also, if these Blocks get used for sidebars, headers or footers down-the-road as is the rough roadmap for the next version that seems like a likely case for every user where they'll be used in something not called a Post or Page.

[noisysocks]

Thanks for tackling this @0aveRyan! Looks good to me 👍

I would like for us to one day show the icon of the underlying block type and perhaps mention it in the description, but this is a fantastic start that we can iterate on.

[0aveRyan]

@noisysocks agreed. one other idea I had was to allow users to write their own reusable block descriptions (stored in the_excerpt) to encourage more succinct Block Names. Is there a roadmap for reusable blocks? Should tickets be opened for these?

[noisysocks]

Is there a roadmap for reusable blocks? Should tickets be opened for these?

There's no roadmap per se, though do feel free to open an issue and tag it with the Reusable Blocks label.