Adds better descriptions for all blocks #6624
Conversation
|
❤️🤘 |
core-blocks/freeform/index.js
Outdated
| @@ -15,7 +15,7 @@ export const name = 'core/freeform'; | |||
| export const settings = { | |||
| title: __( 'Classic' ), | |||
|
|
|||
| description: __( 'The classic editor, in block form.' ), | |||
| description: __( 'It\'s the classic WordPress editor and a it\'s block! Drop the editor right in.' ), | |||
core-blocks/latest-posts/index.js
Outdated
| @@ -15,7 +15,7 @@ export const name = 'core/latest-posts'; | |||
| export const settings = { | |||
| title: __( 'Latest Posts' ), | |||
|
|
|||
| description: __( 'Shows a list of your site\'s most recent posts.' ), | |||
| description: __( 'Display a list your most recent posts.' ), | |||
core-blocks/cover-image/index.js
Outdated
| @@ -63,7 +63,7 @@ export const name = 'core/cover-image'; | |||
| export const settings = { | |||
| title: __( 'Cover Image' ), | |||
|
|
|||
| description: __( 'Cover Image is a bold image block with an optional title.' ), | |||
| description: __( 'Add a full-width image, and layer text over it -- great for headers' ), | |||
There was a problem hiding this comment.
The rest of the items have a full stop. Should this as well?
core-blocks/text-columns/index.js
Outdated
| @@ -27,7 +27,7 @@ export const name = 'core/text-columns'; | |||
| export const settings = { | |||
| title: __( 'Text Columns' ), | |||
|
|
|||
| description: __( 'Add text across columns. This block is experimental' ), | |||
| description: __( 'Add text, and display it in two or more columns. Like a newspaper! This block is experimental' ), | |||
There was a problem hiding this comment.
This one is also missing a full stop.
Fixes review issues found.
|
I added in the changes suggested. To that point going to merge this so we get it in and can do iterations if need. Thanks everyone and particular thanks to @michelleweber for helping us get better copy into Gutenberg ❤️ |
|
This is great! Thanks @michelleweber. I would love to have a section about Block descriptions in the Handbook reference section so that plugin teams could follow your lead. Format specifics (like a full stop at the end) are good but notes on tone/voice would be handy for maintaining consistency between blocks. |
|
I can definitely try to put together some guidelines for descriptions, UI instruction, and error messaging! I'll compile some notes next week, when I get back from the team meetup I'm on. |
| @@ -14,7 +14,7 @@ export const name = 'core/code'; | |||
| export const settings = { | |||
| title: __( 'Code' ), | |||
|
|
|||
| description: __( 'The code block maintains spaces and tabs, great for showing code snippets.' ), | |||
| description: __( 'Add text that respects your spacing and tabs -- perfect for displaying code.' ), | |||
There was a problem hiding this comment.
Add text that respects your spacing and tabs -- perfect for displaying code.
Instead of a faux-em dash, should we use a real em dash — ?
Or am I mistaken in my understanding of -- being more of a convenience since keyboards don't have intended character readily available?
A few other instances of this in the same pull request.
There was a problem hiding this comment.
I fixed one of them in #7196, it would be nice to catch them all.
| @@ -30,7 +30,7 @@ const HOSTS_NO_PREVIEWS = [ 'facebook.com' ]; | |||
|
|
|||
| function getEmbedBlockSettings( { title, description, icon, category = 'embed', transforms, keywords = [] } ) { | |||
| // translators: %s: Name of service (e.g. VideoPress, YouTube) | |||
| const blockDescription = description || sprintf( __( 'Paste URLs from %s to embed the content in this block' ), title ); | |||
| const blockDescription = description || sprintf( __( 'Add a block that displays content pulled from other sites, like Twitter, Instagram or YouTube.' ), title ); | |||
There was a problem hiding this comment.
As of this change, there's no placeholder content in the string, but we still use placeholder substitution (sprintf) and include a translator comment describing the placeholder on the preceding line.
Both of these should have been removed.
Edit: Fix at #13756
Props @michelleweber. Fixes #6623