-
Notifications
You must be signed in to change notification settings - Fork 4.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Refinement and consistency for block descriptions #10919
Comments
Thanks great work! I have a few comments:
|
Thanks @Soean! Great catches.
Edited above to encompass both use cases
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.
Good catch, removed / edited above. |
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. |
There is a new block called |
@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.) |
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:
QuoteI'd go with something that more explicitly describes what the block does, e.g.:
CodeMy 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...
HTMLMentioning "page" here could be potentially confusing, e.g. when a user adds HTML in a post. Suggested edit:
PullquoteI'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...
VerseIt semi-breaks my heart to see the easter-egg haiku gone :)
ButtonI'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:
Spacer"Custom white space" sounds slightly off to me. What do you think about something like...
Or:
Specific embed blocksNo 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! |
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 1 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
|
@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. |
OK, so I did a bit of a thought experiment. I have two variations for each block:
(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
Image
Gallery
Heading
List
Quote
Audio
Cover
File
Video
Code
Classic
HTML
Preformatted
Pullquote
Table
Verse
Button
More
Page break
Separator
Spacer
Shortcode
Archives
Categories
Latest Comments
Latest Posts
Embed
Specific embed blocks (Twitter, YouTube, Instagram, etc.)
|
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. |
This follows the latest suggestions by @alexislloyd in #10919.
We also need a description for the new |
Definitely, I wouldn't want to hurt this process.
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:
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:
Lastly:
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. |
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...
...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):
|
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:
Outside of those above, I don't personally mind the initial suggestions, and in many cases (spacer, page break) are vastly improved. |
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. |
Updated to (I think!) reflect all the comments above :) Let me know if I've missed anything. Updated descriptions are in italics: Paragraph
Image
Gallery
Heading
List
Quote
Audio
Cover
File
Video
Code
Classic
HTML
Preformatted
Pullquote
Table
Media & text
Verse
Button
More
Page break
Separator
Spacer
Shortcode
Archives
Categories
Latest Comments
Latest Posts
Embed
Specific embed blocks (Twitter, YouTube, Instagram, etc.)
|
I really like how these have evolved, @alexislloyd! Moving into micro-nitpicking territory, I had a handful of (minor) additional notes:
Or:
|
Good catches, @benhuberman! I edited directly in the post above to avoid lots of long comments :) |
Anyone for a quick PR to land this on 4.2 ;) |
I am working on a PR... |
While creating the PR #11148 I noticed only column wasn't changed. Current description: |
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. |
Note that there was already a PR in #10971 for this. |
Oh missed it sorry :) |
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. |
This follows the latest suggestions by @alexislloyd in #10919.
This follows the latest suggestions by @alexislloyd in #10919.
Closed by #10971 |
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.Gallery
Display multiple images in an elegantly organized tiled layout.Heading
Introduce topics and help visitors (and search engines!) understand how your content is organized.Paragraph
Add some basic text.List
Numbers, bullets, up to you. Add a list of items.Quote
Maybe someone else said it better -- add some quoted text.Audio
Embed an audio file and a simple audio player.Cover
Add a full-width image, and layer text over it — great for headers.File
Add a link to a file that visitors can download.Video
Embed a video file and a simple video player.Code
Add text that respects your spacing and tabs -- perfect for displaying code.Classic
It’s the classic WordPress editor and it’s a block! Drop the editor right in.HTML
Add your own HTML (and view it right here as you edit!).Preformatted
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.Table
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?)Button
Want visitors to click to subscribe, buy, or read more? Get their attention with a 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.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.Separator
Insert a horizontal line where you want to create a break between ideas.Spacer
Add an element with empty space and custom height.Shortcode
Add a shortcode -- a WordPress-specific snippet of code written between square brackets.Archives
Display a monthly archive of your site’s Posts.Categories
Display a list of all your site’s categories.Latest Comments
Show a list of your site’s most recent comments.Latest 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.Specific embed blocks (Twitter, YouTube, Instagram, etc.)
Add a block that displays content pulled from other sites, like Twitter, Instagram or YouTube.The text was updated successfully, but these errors were encountered: