Refinement and consistency for block descriptions

[alexislloyd]

I've been working on edits to the core block descriptions in order to improve clarity and consistency (issue was flagged by @mtias and @jasmussen).

My goals included starting each description with an action verb, simplifying wording for more concise descriptions, creating a consistent tone, and some minor edits for grammatical consistency (emdashes instead of double hyphens, Oxford commas consistently, etc.) Below are my proposed edits:

Image

• They’re worth 1,000 words! Insert a single image.
• Insert an image from a file or a link.

Gallery

• Display multiple images in an elegantly organized tiled layout.
• Display multiple images in a gallery format.

Heading

• Introduce topics and help visitors (and search engines!) understand how your content is organized.
• Introduce sections to organize content.

Paragraph

• Add some basic text.
• Start writing with simple text.

List

• Numbers, bullets, up to you. Add a list of items.
• Create a bulleted or numbered list.

Quote

• Maybe someone else said it better -- add some quoted text.
• Capture a quote and who said it.

Audio

• Embed an audio file and a simple audio player.
• Embed a simple audio player.

Cover

• Add a full-width image, and layer text over it — great for headers.
• Add an image or video with a text overlay — great for headers.

File

• Add a link to a file that visitors can download.
• Add a link to a downloadable file.

Video

• Embed a video file and a simple video player.
• Embed a video from your media library or upload a new one.

Code

• Add text that respects your spacing and tabs -- perfect for displaying code.
• Capture and display code snippets.

Classic

• It’s the classic WordPress editor and it’s a block! Drop the editor right in.
• Use the classic WordPress editor.

HTML

• Add your own HTML (and view it right here as you edit!).
• Add custom HTML code and preview it right in the page.

Preformatted

• Add text that respects your spacing and tabs, and also allows styling.
• Add text that respects your spacing and tabs, and also allows styling.

Pullquote

• Highlight a quote from your post or page by displaying it as a graphic element.
• Emphasize text in the post or page by displaying it graphically.

Table

• Insert a table -- perfect for sharing charts and data.
• Insert a table — perfect for sharing charts and data.

Verse

• A block for haiku? Why not? Blocks for all the things! (See what we did here?)
• Insert poetry, song lyrics, and more.

Button

• Want visitors to click to subscribe, buy, or read more? Get their attention with a button.
• Get visitors' to take action with a customizable button .

More

• Want to show only part of this post on your blog’s home page? Insert a "More" block where you want the split.
• Define the length of post previews on your home page by inserting this block.

Page break

• This block allows you to set break points on your post. Visitors of your blog are then presented with content split into multiple pages.
• Separate your content into a multi-page experience.

Separator

• Insert a horizontal line where you want to create a break between ideas.
• Create a break between ideas or sections with a horizontal line.

Spacer

• Add an element with empty space and custom height.
• Add custom white space between blocks.

Shortcode

• Add a shortcode -- a WordPress-specific snippet of code written between square brackets.
• Insert additional custom elements with a WordPress shortcode.

Archives

• Display a monthly archive of your site’s Posts.
• Display a monthly archive of your site’s posts.

Categories

• Display a list of all your site’s categories.
• Display a list of your site’s categories.

Latest Comments

• Show a list of your site’s most recent comments.
• Display a list of your site’s most recent comments.

Latest Posts

• Display a list of your most recent posts.
• Display a list of your most recent posts.

Embed

• The Embed block allows you to easily add videos, images, tweets, audio, and other content to your post or page.
• Embed videos, images, tweets, audio, and other content from external sources.

Specific embed blocks (Twitter, YouTube, Instagram, etc.)

• Add a block that displays content pulled from other sites, like Twitter, Instagram or YouTube.
• Embed [type] content. (For example, the Twitter block should say "Embed Twitter content."

[Soean]

Thanks great work!

I have a few comments:

• Cover image -> Cover in Rename cover image to cover; Add video in cover block; #10659. Now you are also able to use videos
  Add an image or video with a text overlay — great for headers.?
• Video block doesn't work with YouTube or Vimeo links
• There is no Products block in WordPress by default

[alexislloyd]

Thanks @Soean! Great catches.

Cover image -> Cover in #10659. Now you are also able to use videos

Edited above to encompass both use cases

Video block doesn't work with YouTube or Vimeo links

I updated the description above, but there's a larger UX issue here. Since the placeholder allows you to add via a URL, I think users will assume that they can add external source links.

There is no Products block in WordPress by default

Good catch, removed / edited above.

[Soean]

Since the placeholder allows you to add via a URL, I think users will assume that they can add external source links.

You can add an external video via URL. This URL has to be the URL to the video file, not a URL to a page which contains a video player.

We have a ticket about this UX issue #6824.

[Soean]

There is a new block called Media & Text added in #9416. The block has no description yet.

[benhuberman]

@alexislloyd most of these edits look/sound solid to me on the copy level (I'll note a couple of small things I'd tweak in a separate comment). My main high-level concern is that in many cases -- like the Verse, Image, Heading, and List blocks, to name a few -- the consistent verb-first format and general push to trim the copy comes at the expense of warmth / personality, something on which @michelleweber worked quite intensively with @karmatosed a few months ago (I believe this is the relevant PR).

I wasn't closely engaged with that process, but there seemed to be excitement (and a wide consensus) about the opportunity to inject a more conversational voice into Gutenberg from the get-go, something that has often been missing from legacy WordPress UI. So while iterating on existing copy is a great idea, I wonder if there's room to discuss the general direction we aim to go in with voice here. (Michelle is offline for the next couple of weeks, but I wonder if @karmatosed might be able to provide additional insight/context.)

[benhuberman]

My previous comment around voice notwithstanding, there were a couple of small things I'd suggest we tweak in the current set of suggested descriptions:

Heading

"Introduce sections to organize content" sounded a bit confusing, since it doesn't really mention what the heading actually does / look like. Suggested edit:

Add a short description or highlight to introduce new sections and better organize content.

Quote

I'd go with something that more explicitly describes what the block does, e.g.:

Give quoted text greater visual emphasis.

Code

My sense is that preserving spacing/tabs is key to understanding this function (especially for anyone who's not sure what a "code snippet" is), so maybe something lile...

Display code snippets that respect your original spacing and tabs.

HTML

Mentioning "page" here could be potentially confusing, e.g. when a user adds HTML in a post. Suggested edit:

Add custom HTML code and preview it as you edit.

Pullquote

I'm not sure "displaying it graphically" is quite clear, and veers quite close to jargon (the original "graphic element" might be in that general territory as well). Maybe...

Give special visual emphasis to a quote from your text.

Verse

It semi-breaks my heart to see the easter-egg haiku gone :)
In case you'd consider a format-respecting alternative, here's one:

Insert poetry. Use special spacing formats. Or quote song lyrics.

Button

I'd swap "get" with a more specific verb, and also avoid "customizable" if we can. (There was also an errant apostrophe in the new edit.) So, something like:

Prompt visitors to take action with a custom button.

Spacer

"Custom white space" sounds slightly off to me. What do you think about something like...

Add white space between blocks and define its height.

Or:

Add and define the height of white space between blocks.

Specific embed blocks

No objections to the proposed copy, though if there's a finite, not-too-overwhelming number of these embed blocks, it would sound significantly better if we use a specific noun rather than use "content" -- e.g. "Embed a tweet," "Embed a Facebook post," "Embed an Instagram story," etc.

Happy to discuss further any of these suggested edits if they generate any questions or concerns!

[mcsf]

This is an interesting conversation, especially the question of voice as brought up by @benhuberman.

---

Anecdotally, I quite preferred the previous generation of block descriptions. My favourite was possibly the one for Quote (Quote. In quoting others, we cite ourselves. (Julio Cortázar)). On the surface, that copy set could have seemed more neutral or colder — with some emphasis on directness (Shows a list of your site's categories.) and avoidance of possessive forms (Use the separator to indicate a thematic change in the content.) — but, to me, it did read as a humanised interface. That's because there was a clear voice, but one with a very different style.

Perhaps, in that subjectively blasé detachment, I heard the voice of a product that already knew me well enough that it didn't need to greet me. This, to me, instilled a sense of mutual understanding with the product, so much so that it would let me in on its subtle humor (Tables. Best used for tabular data.).

Conversely — to play Devil's advocate — a copy that "tries" too much will put me off a little.

---

By this detour I meant to come to this conclusion: that a single opinionated ¹ voice will never work for the millions of interlocutors that will be using Gutenberg. For this reason, I think there's a lot of merit in @alexislloyd's proposed revision: it's consistent, direct, avoids making assumptions (e.g. Add some basic text. is problematic to me, because of the assumption that the text would be basic, or that other block types would prevail).

On a secondary note, there are also greater internationalisation challenges in a less neutral copy.

Footnotes

1. I use opinionated loosely to mean that a voice carries (a) certain tone(s), etc. ↩

[alexislloyd]

@benhuberman and @mcsf, this is such a thoughtful set of comments! I definitely see the argument for injecting personality and a bit of playfulness into the tone. I think it can bring warmth to a product experience that is otherwise very functional.

My main concern with the previous state of the descriptions was not so much the tone but the inconsistency of tone. Neutralizing some of the more playful texts was a way of making them all feel part of a coherent whole.

That said, I took a stab at seeing if I could make the more playful tone consistent throughout in response to this thread, and I found that there were a lot of moments where it got in the way of clearly explaining what the block was for. There was tension between the functional and expressive needs. I also worry about @mcsf's point about internationalisation, especially if we start using idioms.

Let me take another pass and see if we can find a middle ground that's not too dry but still consistent and clear.

[alexislloyd]

OK, so I did a bit of a thought experiment. I have two variations for each block:

• The first bullet for each block is a more neutral description (but I tried to make them somewhat less dry than previously).
• The second bullet is taking the playful / conversational approach and applying it consistently throughout.

(While I'm sure we could debate about the specific wording in the second examples, I think this is useful in showing the overall effect.)

Though there are a few individual moments where the second approach is nice, overall, I find that a) it can feel a bit like it's "trying too hard" / borders on cheesy, and b) it's definitely less compelling in providing a clear explanation of what the block does. I'm showing both here so everyone can see it in practice, but I feel strongly that we should go with the more neutral descriptions, for the sake of both clarity and tone. I think the primary purpose of the descriptions should be to clarify the block's function to the user, and the first approach seems more successful there.

Paragraph

• Start with the building block of all narrative.
• Start with the building block of all narrative.
  (this seemed to work in both instances :)

Image

• Insert an image for visual color.
• They say they're worth 1,000 words.

Gallery

• Display multiple images in a rich gallery.
• When one image just isn't enough.

Heading

• Introduce new sections and organize content.
• What's this part about? Tell us with a heading.

List

• Create a bulleted or numbered list
• Numbers or bullets, lists make everyone happy.

Quote

• Give quoted text visual emphasis.
• In quoting others, we cite ourselves. — Julio Cortázar

Audio

• Embed a simple audio player.
• When your site needs some sound.

Cover

• Add an image or video with a text overlay — great for headers.
• Make a statement with bold collages of text & image.

File

• Add a link to a downloadable file.
• Get your visitors what they need with a downloadable file.

Video

• Embed a video from your media library or upload a new one.
• Immerse your viewers with embedded video.

Code

• Display code snippets that respect your spacing and tabs.
• Show how it all works with with code snippets.

Classic

• Use the classic WordPress editor.
• Get retro with the classic WordPress editor.

HTML

• Add custom HTML code and preview it as you edit.
• Customize like an expert with HTML code.

Preformatted

• Add text that respects your spacing and tabs, and also allows styling.
• Shows respect to your spacing and tabs.

Pullquote

• Give special visual emphasis to a quote from your text.
• Say it bigger and bolder with a pullquote.

Table

• Insert a table — perfect for sharing charts and data.
• Make your charts & data shine with tables.

Verse

• Insert haiku. Use special spacing formats. Or quote song lyrics. (See what we did here?)
• A block for haiku? Why not? Blocks for all the things! (See what we did here?)

Button

• Prompt visitors to take action with a custom button.
• Big and clickable for all your most important actions.

More

• Want to show only an excerpt of this post on your home page? Use this block to define where you want the separation.
• Want to show only an excerpt of this post on your home page? Use this block to define and separate.

Page break

• Separate your content into a multi-page experience.
• Reduce the scroll with a multi-page experience.

Separator

• Create a break between ideas or sections with a horizontal line.
• A simple line for spacing and flow.

Spacer

• Add white space between blocks and customize its height.
• White space is beautiful.

Shortcode

• Insert additional custom elements with a WordPress shortcode.
• Classic WordPress shortcodes in a shiny new block.

Archives

• Display a monthly archive of your posts.

Categories

• Display a list of all categories.

Latest Comments

• Display a list of your most recent comments.

Latest Posts

• Display a list of your most recent posts.

Embed

• Embed videos, images, tweets, audio, and other content from external sources.

Specific embed blocks (Twitter, YouTube, Instagram, etc.)

• If the content format has its own noun, then use "Embed a tweet", "embed a Facebook post", etc. If not, then default to "Embed Kickstarter content", "embed Mixcloud content", etc.

[karmatosed]

I wonder if @karmatosed might be able to provide additional insight/context.

Sure, I still feel having a friendly tone is important. Reading through this I can see where we perhaps can balance between that and have more clarity. I am checking myself but fairly sure everyone that was excited with the tone would be excited to find both increased usability and a friendly nature there.

I have to say this is great to read through as the original work didn't have an eye to translation and that is something we can do now. What for example @mcsf (sorry asking) do you feel about the last round of suggestions for translation?

My only concern I have to voice is whatever we do getting this in soon would be a matter of urgency.

[Soean]

We also need a description for the new Media & Text block.

[mcsf]

My only concern I have to voice is whatever we do getting this in soon would be a matter of urgency.

Definitely, I wouldn't want to hurt this process.

What for example @mcsf (sorry asking) do you feel about the last round of suggestions for translation?

Do you mean the very latest? Roughly all the neutral descriptions seem straightforward to translate, by virtue of their own straightforward character. As for their conversational counterparts, they vary a lot. A lot of things are encoded in English that we take for granted. For instance:

• White space is beautiful causes impact for its rhythm, but how can this not be lost if a language doesn't have a clear term for "white space", or if multiple connotative terms exist for "beautiful" that associate poorly with "white space"?
• What about idioms? 1,000 words refers to a particularly well known idiom in English, but feels out of place elsewhere (and what of any language marked by a different relationship with the single word?).
• Many instances where there is either a possessive form ("your posts") or verb conjugated in the user's person ("get retro", and to a lesser extent more "normal" imperatives) can uncover something that is a preexisting challenge for WordPress (and any software) regarding inflexion for gender, formality and number. In English, the word "you" may refer to one of any gender, doesn't assume a formal or informal tone, and may refer to one or many people; this varies wildly in other languages. This last point is less relevant, since it's a challenge that just goes with software translation, but it's worth raising awareness to it, and to the fact that a phrase like "Display a list of posts" can, in the course of translation, be fashioned in more ways (switch from imperative to infinitive, adopt a UI-style sentence structure, etc.) than a conversational one.

The last point brings me to a general note: it's obviously possible to translate just about any strings we choose. Just look at translated literature. But, the more we deviate from neutral and clear, the harder it becomes to translate, leading to one of two results:

• A high-quality translator is needed that can exercise creative liberty to make the conversational phrase as idiomatic and neutral in the target language.
• Such a translator cannot be found, or cannot afford to spend the added time that the strings demand, and poor translations will be made — either because they remained too literal to the point of sounding artificial or cryptic, or because the wrong kind of liberty was taken.

Lastly:

• In this issue we have the luxury of rethinking all the block descriptions at once in order to produce consistent copy. We cannot assume, however, that only a single person or cohesive team of translators can tackle the project in every locale. Whereas a neutral style would minimise the effects of this diversity, a conversational one would exacerbate it, more easily leading to incoherent language.
• If we consider that translators out there are probably also in a rush to get the locales ready for 5.0, that's another argument in favour of the neutral copy.

On a more positive note, I'll stress that, given enough time, locales do undergo community efforts to unify the style and improve overall quality. But my personal opinion is that we should go for the neutral language now, and perhaps in 5.1 rethink this.

P.S.: please stop me, I become insufferable when prompted about languages.

[benhuberman]

Thank you for the thoughtful discussion @mcsf and @karmatosed, and for carefully laying out the stakes in your thought experiment, @alexislloyd!

I appreciate how the new set of "more neutral" descriptions feels a couple of notches warmer than the previous iteration. That, in conjunction with the concerns raised above around urgency and internationalization, lead me to see it as a reasonable approach to take at this point. I have a long-standing concern that the need to translate all strings often prevents us -- preemptively -- from taking risks and making bold(er) voice choices, but in this particular case I agree that it would make sense to lean in a more risk-averse direction.

One small note -- the new edit for the Verse block...

Insert haiku. Use special spacing formats. Or quote song lyrics. (See what we did here?)

...is no longer an easter-egg haiku. This isn't quite a life-or-death issue, but in case we wanted to preserve that bit of playfulness, my initial edit kept the 5-7-5 format (but without calling attention to itself):

Insert poetry. Use special spacing formats. Or quote song lyrics.

[jasmussen]

What a wonderful discussion here. I will try and add very little to it so as to not start painting a fence here, but just chime in to echo that both the initial goal (ensuring consistency of tone) is noble and good, but marrying that with some "warmth" as suggested by Ben seems good.

But it's an important balance to find. While we want to keep some warmth, we also don't want to get too conversational. An important thing to remember is that we can't know what exactly the user is writing about, it could be incredibly sad or otherwise emotionally loaded, at which point too much playfulness or joking becomes tone-deaf.

Perhaps the balance is to veer more closely to what Alexis initially suggested for most blocks, but add a little spice for a few of them. For example it's probably fine that the Image block says "Insert an image from a file or a link", but it would be nice to keep the haiku format for the verse, as historically WordPress has had a fling with haikus.

Specifically:

• Heading block: I would suggest it is important to mention search engines here, because the semantics they can provide are important for SEO but in fact also accessibility. Doesn't have to be a big namedrop, and we can drop the exclamation mark if that matches the tone better.
• I miss the use of an actual quote for the Quote block description, and I think the Cortazar one was oddly appropriate. Perhaps we could combine the two: "Capture a quote and who said it. _In quoting others, we cite ourselves. — Julio Cortázar".
• I dig Ben's verse block suggestion: "Insert poetry. Use special spacing formats. Or quote song lyrics." — the "see what we did there" becomes too conversational for me.

Outside of those above, I don't personally mind the initial suggestions, and in many cases (spacer, page break) are vastly improved.

[mtias]

It is great to see all the care being put into this, I think it matters. It is indeed a fine balance to meet. (I also thought the Cortázar quote was a nice touch, for example.)

Another point to consider, apart from translations, is documenting guidelines so that 3rd party block authors can create blocks that feel part of a cohesive whole.

[alexislloyd]

Updated to (I think!) reflect all the comments above :) Let me know if I've missed anything. Updated descriptions are in italics:

Paragraph

• Start with the building block of all narrative.

Image

• Insert an image to make a visual statement.

Gallery

• Display multiple images in a rich gallery.

Heading

• Introduce new sections and organize content to help visitors (and search engines) understand the structure of your content.

List

• Create a bulleted or numbered list.

Quote

• Give quoted text visual emphasis.
  "In quoting others, we cite ourselves." — Julio Cortázar

Audio

• Embed a simple audio player.

Cover

• Add an image or video with a text overlay — great for headers.

File

• Add a link to a downloadable file.

Video

• Embed a video from your media library or upload a new one.

Code

• Display code snippets that respect your spacing and tabs.

Classic

• Use the classic WordPress editor.

HTML

• Add custom HTML code and preview it as you edit.

Preformatted

• Add text that respects your spacing and tabs, and also allows styling.

Pullquote

• Give special visual emphasis to a quote from your text.

Table

• Insert a table — perfect for sharing charts and data.

Media & text

• Set media and words side-by-side media for a richer layout.

Verse

• Insert poetry. Use special spacing formats. Or quote song lyrics.

Button

• Prompt visitors to take action with a custom button.

More

• Want to show only an excerpt of this post on your home page? Use this block to define where you want the separation.

Page break

• Separate your content into a multi-page experience.

Separator

• Create a break between ideas or sections with a horizontal line.

Spacer

• Add white space between blocks and customize its height.

Shortcode

• Insert additional custom elements with a WordPress shortcode.

Archives

• Display a monthly archive of your posts.

Categories

• Display a list of all categories.

Latest Comments

• Display a list of your most recent comments.

Latest Posts

• Display a list of your most recent posts.

Embed

• Embed videos, images, tweets, audio, and other content from external sources.

Specific embed blocks (Twitter, YouTube, Instagram, etc.)

• If the content format has its own noun, then use "Embed a tweet", "embed a Facebook post", etc. If not, then default to "Embed Kickstarter content", "embed Mixcloud content", etc.

[benhuberman]

I really like how these have evolved, @alexislloyd!

Moving into micro-nitpicking territory, I had a handful of (minor) additional notes:

• Image: "visual color" sounds a tad off to me, as I can't think of color that isn't visual; this also doesn't quite apply to B&W/monochrome photography. How about:

Insert an image to make a visual statement.

Or:

Insert an image to make your point visually.

• Heading: "your site structure" isn't quite right, since headings organize content within discrete "units" (posts, pages). We could reword a bit, e.g.:

Introduce new sections and organize them to help visitors (and search engines) understand your content's structure.

• Lists: terminal punctuation is missing.

• Media & Text: this one departs from the verb-first format, and I don't think it's necessarily justified. I'm also not sure the connection between "easy" and "layout" is intuitively clear. We could address these with a minor rewording:

Set media and words side-by-side for a richer layout.

[alexislloyd]

Good catches, @benhuberman! I edited directly in the post above to avoid lots of long comments :)

[youknowriad]

Anyone for a quick PR to land this on 4.2 ;)

[Soean]

I am working on a PR...

[Soean]

While creating the PR #11148 I noticed only column wasn't changed. Current description:
Add a block that displays content in multiple columns, then add whatever content blocks you’d like.

[StaggerLeee]

Agree, it would be improved with new suggestions.

Just, Quote. It is design-layout theme block to emphasize something. Not only quotes from other humans.

[ocean90]

Note that there was already a PR in #10971 for this.

[youknowriad]

Oh missed it sorry :)

[karmatosed]

Ideally we should iterate on #10971 over have a new one but I am ok if we do want to close that one, as it was me that made me so all good.

[youknowriad]

Closed by #10971