Closed alexislloyd closed 5 years ago
Soean
commented
5 years ago Thanks great work!
I have a few comments:
Add an image or video with a text overlay — great for headers.?
alexislloyd
commented
5 years ago 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
commented
5 years ago 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
commented
5 years ago There is a new block called Media & Text added in #9416. The block has no description yet.
benhuberman
commented
5 years ago @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
commented
5 years ago 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:
"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.
I'd go with something that more explicitly describes what the block does, e.g.:
Give quoted text greater visual emphasis.
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.
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.
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.
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.
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.
"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.
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
commented
5 years ago 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.
[^1]: I use opinionated loosely to mean that a voice carries (a) certain tone(s), etc.
alexislloyd
commented
5 years ago @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
commented
5 years ago 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.
karmatosed
commented
5 years ago 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
commented
5 years ago We also need a description for the new Media & Text block.
mcsf
commented
5 years ago 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:
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.
benhuberman
commented
5 years ago 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
commented
5 years ago 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.
mtias
commented
5 years ago 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
commented
5 years ago Updated to (I think!) reflect all the comments above :) Let me know if I've missed anything. Updated descriptions are in italics:
benhuberman
commented
5 years ago I really like how these have evolved, @alexislloyd!
Moving into micro-nitpicking territory, I had a handful of (minor) additional notes:
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
commented
5 years ago Good catches, @benhuberman! I edited directly in the post above to avoid lots of long comments :)
youknowriad
commented
5 years ago Anyone for a quick PR to land this on 4.2 ;)
Soean
commented
5 years ago I am working on a PR...
Soean
commented
5 years ago 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
commented
5 years ago 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
commented
5 years ago Note that there was already a PR in #10971 for this.
youknowriad
commented
5 years ago Oh missed it sorry :)
karmatosed
commented
5 years ago 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
commented
5 years ago 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.