Skip to content
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

Compile a list of possible block-specific tips #16595

Open
kjellr opened this issue Jul 15, 2019 · 9 comments

Comments

@kjellr
Copy link
Contributor

commented Jul 15, 2019

Whether we end up placing them inside of block UI/placeholders (#16315), in the block library (#16592), or in the sidebar (#16594), let's use this thread to compile a list of possible "Tips" for the current set of Core blocks. A few examples to get us started:

  • [Image Block] Looking to add multiple images? Try the Gallery block.
  • [Image Block] If you'd like to add text on top of your image, try the Cover block.
  • [List Block] Quickly indent a new list item by starting it with a space.

@kjellr kjellr added Blocks NUX labels Jul 15, 2019

@mtias mtias added the [Type] Copy label Jul 15, 2019

@karmatosed

This comment has been minimized.

Copy link
Member

commented Jul 17, 2019

Could this also extend to if someone is using a block and another could be good to use with it? Sort of like "oh hey you added 3 images, what about the gallery block?". Similarly, what about recommending blocks that follow patterns. Maybe if people use quote block they likely use another type of block (we'd need data).

@mapk

This comment has been minimized.

Copy link
Contributor

commented Jul 17, 2019

[Cover block] Add text, headings, or buttons to this block. (do people realize they can add only certain blocks here? Do they know they can add a button too?)

[Media+Text block] You can swap the image to the right side in the block's toolbar. (Is this easily discoverable for people?)

@kjellr

This comment has been minimized.

Copy link
Contributor Author

commented Jul 18, 2019

All good suggestions. I definitely think suggesting other blocks is a good idea.

Here are a few other tips gathered from re-watching the latest round of user testing videos on make.wordpress.org/test:

  • [Any Block] Use the block alignment options to move blocks to the left or right.*
  • [Any Block] Use Block Styles in the sidebar to try alternate versions of this block.**
  • [Image Block] To add text on top of your image, convert to a Cover block.
  • [Image Block] To add more than one image at once, try using a Gallery block.

*We should include the icon in this message.
**This is also available in the block switcher, but I think "the sidebar" is an easier destination to direct people to.

@kjellr

This comment has been minimized.

Copy link
Contributor Author

commented Jul 31, 2019

Here's another set of these, created by just going through Gutenberg's "Common Blocks":

Common Blocks

  • [Any Block] Use the block's toolbar icon to transform your block into another type of block.
  • [Paragraph] Adjust the paragraph's font size.
  • [Paragraph] For an impactful beginning to your paragraph, try enabling a drop cap.
  • [Quote] The quote block comes with an extra "Large" style variant.
  • [Image] You can add alternative text for your images to make them more accessible.
  • [Gallery] If you don't want your gallery images auto-cropped to align with each other, you can turn off that setting off.
  • [Gallery] A gallery can have up to 8 columns.
  • Video The video block accepts video uploads in the following formats: MP4, M4V, MOV, WMV, AVI, MPG, OGV, 3GP, and 3G2. (This should be fact-checked. 🙂 )
  • [Video] To embed a video from YouTube, just press the "Insert from URL" button and paste in the web address. (This can be duplicated for other video services)
  • [Cover] Try the focal point picker to better control the crop of your image.
  • [Cover] You can adjust the Cover's overlay color to be whatever you'd like.
  • [Cover] The Cover block supports both images and video.
  • [Cover] You can place any other type of block inside of a Cover block.
  • [List] Use space or backspace to indent or outdent a new list item.
  • [Audio] The audio block accepts uploads in the mp3, m4a, ogg, wav, and wma formats.
  • [Audio] To embed a song or album from Spotify, just press the "Insert from URL" button and paste in the share URL. (This can be duplicated for other music services)
  • [File] The download button can be turned on and off.

As I was running through these, I ran into a nomenclature issue when it came to the "block sidebar". On small screens, that isn't a sidebar at all, and calling it that also doesn't work well with screen readers either.

Depending on where these show up, @sarahmonster suggested we might avoid referring to the location entirely. For instance, something like:

Add alternative text for your images in the Block Tab of the Settings Sidebar.

... could instead be something like:

You can add alternative text for your images to make them more accessible.

Once users know where block settings live, they'll (hopefully!) know where to look for that sort of setting anyway — these block-specific tips may not be the best place to teach folks where things live.

I'm going to keep going through more blocks to grow this list later, but I'd love for some further thoughts on how/if we should refer to locations like the sidebar + toolbar in these tips.

Thanks!

@kjellr

This comment has been minimized.

Copy link
Contributor Author

commented Aug 1, 2019

More tips for the Formatting, Layout Elements, Widget, and Embed blocks.

I tried to include at least tone for each block (even when the functionality was relatively limited, as in the case of the Spacer block. 😄). I did not write tips for each of the Embeds, since those don't usually come with extra functionality.

I think this covers every one of the core blocks. Anything missing? Id love some feedback on these, as well as what other tips we should provide.


Formatting Blocks:

  • [Code] Use the Custom HTML block if you'd like to render HTML.
  • [Code] If you don't want your code to wrap, try the Preformatted block instead.
  • [Preformatted] Unlike the Code block, the Preformatted block will preserve line breaks.
  • [Preformatted] If you're looking to write poetry or prose but preserve line breaks, try the Verse block instead.
  • [Preformatted] Unlike the code block, the Preformatted block allows you to use text formatting.
  • [Classic] The content of classic blocks can be converted into standard blocks.
  • [Custom HTML] For simple code snippets, use the Code block instead.
  • [Custom HTML] The Custom HTML block will only accept HTML and inline CSS.
  • [Pullquote] The Pullquote block comes with a style variation that lets you place the text against a solid color.
  • [Pullquote] You can customize the color used in the pullquote block.
  • [Pullquote] If your theme supports it, you can set a pullquote to wide or full-width for extra emphasis.
  • [Table] The table block can be use fixed-width or variable-width table cells.
  • [Table] Try assigning a background color to your table cells.
  • [Table] The table block has a "Stripes" style variation for that alternates the color of its rows.
  • [Verse] The Verse block will preserve all of your line breaks.

Layout Elements

  • [Button] The Button block lets you choose from rounded, outline, and squared styles.
  • [Button] The button can be configured to open its link in a new tab.
  • [Columns] You can set the vertical alignment of items within the columns block.
  • [Columns] Select an individual column to adjust its width.
  • [Columns] The Columns block supports up to 6 columns by default.
  • [Group] The Group block can contain any other type of block (including other Group blocks!).
  • [Group] The Group block is a great way to add a background color behind multiple blocks at a once.
  • [Media & Text] The Media and Text allows you to place any kind of block opposite an image or video.
  • [Media & Text] The image or video can be placed on either side of the text in the Media & Text block.
  • [Media & Text] Try toggling "Stack on mobile" for a mobile-friendlier block layout.
  • [Media & Text] If you're using an extra tall image in the Media & Text block, try the "Crop image to fill entire column" option.
  • [More] Each post or page can only contain one More block.
  • [More] You can click to edit the "Read more" label for the More block.
  • [Page Break] You can use as many page breaks as you'd like in your document.
  • [Separator] The separator allows you to chose from short, wide, and dotted styles.
  • [Separator] You can change the color of separator block.
  • [Spacer] You can specify an exact pixel height for the space block.

Widgets

  • [Shortcode] Many legacy shortcodes are now available as blocks.
  • [Archives] The Archives block can be shown as a list or a dropdown.
  • [Archives] The Archives block can show post counts for each month.
  • [Calendar] The calendar can be optionally shown wide or full-width.
  • [Categories] The Catetgories block can appear as a list or a dropdown.
  • [Categories] The Categories block can show or hide category hierarchy.
  • [Categories] The Categories block can show post counts for each category.
  • [Latest Comments] The Latest Comments block can display up to 100 comments.
  • [Latest Comments] You can toggle off the excerpt in the Latest Comments block if you'd just like a list of comment links.
  • [Latest Posts] Latest Posts can be shown as a list or a grid.
  • [Latest Posts] Latest Posts can display either a list of titles, or the post content itself.
  • [Latest Posts] The Latest Posts block can display up to 100 posts.
  • [Latest Posts] The Latest Posts block can show only posts from a category you choose.
  • [RSS] The RSS block can show up to 10 items per feed.
  • [RSS] The RSS block can optionally show the author, date, and excerpt.
  • [RSS] The RSS block can show posts as a list or a grid.
  • [Search] You can customize the placeholder text and title of the Search block.
  • [Tag Cloud] The Tag cloud can display either tags or categories.
  • [Categories] The Tag cloud can show post counts alongside each item.

Embeds

  • [Embed] Paste any URL into the Embed block, and WordPress will try to embed it.
@mtias

This comment has been minimized.

Copy link
Contributor

commented Aug 6, 2019

Great start, @kjellr. I think we should start with just a handful to make sure they are adding considerable value. In that sense, I think these should be about things that are not obvious. (The indenting on a list is a good one.)

For example, if you are adding an image we could tell the user how to get a "side by side" display of two images by converting it into a gallery.

Things that just explain the common tools (toolbar items, block inspector) seem less relevant as we should always be explaining these in the context of the tools themselves.

@kjellr

This comment has been minimized.

Copy link
Contributor Author

commented Aug 6, 2019

Here's a more refined list:

  • [General] When writing, type / to quickly insert a new block.
  • [Image] Add alternative text to your images to make them more accessible.
  • [Image] Use a Cover block to add text on top of your image.
  • [Image] To place two images side by side, convert them to a Gallery.
  • Video The video block accepts uploads in the MP4, M4V, WebM, OGV, WMV, and FLV formats.
  • [Cover] You can place any other type of block inside of a Cover block.
  • [List] Press space or backspace to indent or outdent a new list item.
  • [Audio] The audio block accepts uploads in the MP3, M4A, OGG, WAV, and WMA formats.
  • [Code] If you don't want your code to wrap, try the Preformatted block instead.
  • [Classic] The content of classic blocks can be converted into standard blocks.
  • [Custom HTML] For embedded code snippets, use the Code block instead.
  • [Verse] The Verse block will preserve all line breaks.
  • [Group] You can place any other type of block inside of a Group block.
  • [Group] Use the Group block to add a background color behind multiple blocks at once.
  • [More] Each post or page can only contain one More block.

Or, if we really want to trim down to just a handful:

  • [General] When writing, type / to quickly insert a new block.
  • [Image] Add alternative text to your images to make them more accessible.
  • [Image] To place two images side by side, convert them to a Gallery.
  • [List] Press space or backspace to indent or outdent a new list item.
  • [Group] Use the Group block to add a background color behind multiple blocks at once.

If these sound about right, we can see about having the copy reviewed.

@mapk

This comment has been minimized.

Copy link
Contributor

commented Aug 8, 2019

That refined list of tips looks really good, Kjell. Will all these be visible from within the Inserter panel?

@kjellr

This comment has been minimized.

Copy link
Contributor Author

commented Aug 9, 2019

Hopefully, yes! Once #16813 is merged, we can follow up and include these when you hover over the blocks they reference.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.