Tracking: Blocks page v1 and beyond

[annezazu]

To pull together the initial iteration of the blocks page, I'm gathering feedback here with what's known to update for a quick iteration:

Now

• Ensuring links are updated to work better with locale updates.
• Some light copy changes thanks to some editorial help from Peter Rubin.
• Update the code example to what was kindly provided previously and ensure it aligns with accessibility feedback.
• Remove alt text from block icons. Completed by @ryelle.
• Update labels of links based on feedback.
• Wrap arrows for links in aria-hidden. @ryelle can you handle?

Next

For design:

• Consider list arrangement for block section/improve accessibility there based on design and a11y feedback.
• Ensure visuals and illustrations are language neutral to better hold up across languages.
• Add some sort of a visual(s) that better represents the connection between blocks > patterns > themes (rough mockup), including an updated hero image.

For dev/other:

• Consider enabling the code syntax block plugin that is used on the developer redesign and porting over the "copy" button functionality (like this example).
• Bring back a section that emphasizes user friendliness (insert, transform, style, etc) and ensure it establishes the user friendliness closer to the top. Context.
• Consider how best to use WP Sandbox to have folks try out more of what’s discussed here.
• Integrate something like the blockbook project into the experience, perhaps using WP Sandbox.
• Connect broader use of blocks to the Showcase work to highlight what's been done with blocks.
• Consider how best to include (and whether to include) this newest gutenberg as a framework doc site: Bootstrap a documentation website tailored towards the usage of Gutenberg outside WordPress gutenberg#54375

[annezazu]

Here's the copy feedback I kindly got via DM:

• WordPress' Secret Power should be in sentence case, since it’s a section heading and not a page heading (and is also the only section heading formatted in title case): WordPress' secret power
• WordPress is built on blocks with the ability to create every part of your site using this visual experience... This graf has a little word salad, might rework it to: Blocks are the visual foundation of WordPress, and can be used to create and manage every part of your site. They're also easier than you think. Learn how to edit a block and you learn how to use all of WordPress—without having to write code. (that’s an em dash in there, even if it looks like a regular hyphen)
• Drag and drop interface —> drag-and-drop interface (since it’s a compound adjective).
• As a unified and open syntax, they're easy to understand by editors, browsers, and even AI. —> As a unified and open syntax, they're easily understood by editors, browsers, and even AI.

[annezazu]

Completed the following and have an update waiting to be synced:

• Ensured links are updated to work better with locale updates.
• Made some light copy changes thanks to some editorial help from Peter Rubin.
• Updated the code example to what was kindly provided previously and ensure it aligns with accessibility feedback.
• Updated labels of links based on feedback.

These two items remain for an additional update this week:

• Consider list arrangement for block section/improve accessibility there based on design and a11y feedback.
• Wrap arrows for links in aria-hidden.

[ryelle]

Added a PR to the parent theme to hide the arrows on all child themes (including this one): WordPress/wporg-parent-2021#94

@annezazu regarding the code block, I'm still seeing marks throughout, it looks like that's meant to be a syntax highlighting by applying text color. We could try enabling the code syntax block plugin that is used on the developer redesign (this page has an example), and then maybe also port over the "copy" button functionality (like this example). For now, I think the text colors should be removed.

[ryelle]

Synced the latest content in beba657, deploying that now.

[annezazu]

Ah got it. That's my mistake. I have updated the page to remove the text colors -- can you handle an update once more? @ryelle

Of note, I've also updated this overall issue into "Now" and "Next" to better structure what can be fixed right now and what will need to be considered further into the future for another iteration.

[alexstine]

@ryelle Not to distract from this discussion, but that redesign test page has an alarming number of accessibility issues. Where is that work currently being tracked? Is it early on enough that I shouldn't be reporting such bugs? I never have a feel for how fast stuff moves in this project until something hits production and that's extremely frustrating. I am sure some of these issues probably came from the old codex and developer resources days but if we're redesigning, no reason the ccode shouldn't be fixed.

[ryelle]

@alexstine We halted work on that site a few months ago, and are just now restarting, so now would be a great time to add that feedback. That project is tracked in this repo: https://github.com/WordPress/wporg-developer/

[annezazu]

After adding a more comprehensive "next" section and receiving more feedback, I've updated the title of this issue to indicate a larger iteration in the future.

[annezazu]

With the Showcase launching on the 18th, I want to do a super minor update in this section here to connect the two, likely just as a simple button:

Right now, I'm leaning towards something simple like this:

Curious to hear what @marko-srb thinks!

[marko-srb]

Hey @annezazu,

That works, I can add the button and the sentence. I believe we want to update this only after the Showcase is out (Oct 18th), correct?

[annezazu]

That's correct! Thank you 🥳

[pablohoneyhoney]

Good to see this out!

In general, great as a first iteration. A few thoughts for bettering:

• There’s something playful and engaging about larger imagery and animations, like https://order.design/project/block-by-block; ours feel a bit too boxy (even if pun is intended).
• Mobile is not great, even less appealing, images are super small, not thought for that environment.
• Headings and paragraphs aren’t well aligned.

Content wise:

• There’s a hint at what you can do with blocks but minimal, needs more focus and amplitude on that.
• Same with block types, feels limiting to only surface eight.
• It could have a CTA on top.
• The patterns don’t render high-res on my side.

[marko-srb]

@annezazu

I've just push the update here.

@adamwoodnz can we get this update after the Showcase is out? I can ping again for timing (should be on Thursday this week), just want to make sure this lands on Neso's table and it happens soon after the Showcase i2 is published...

---screenshot preview---

Thanks!

CC: @jasmussen

[annezazu]

Bringing a question/comment I've seen referenced a few times around this effort: What is the role of this page compared to /gutenberg? How can we consolidate and distinguish these efforts? As a result, I've kicked off this open discussion and wanted to cross link to this more intentionally as it's something that might influence future iterations depending on what comes up: #379

[annezazu]

@marko-srb we've gotten some direction around /blocks 🌟 and how best to distinguish from /gutenberg going forward:

He kindly clarified that /blocks is meant to be about how WordPress uses blocks, the block directory, and an introduction for developers who want to build with blocks

I think this simplifies what we need to do into a few sections. At a high level:

• Introducing blocks
• WordPress' secret power (CTA: try blocks live powered by playground rather than /gutenberg)
• Explore blocks (CTA: block directory https://wordpress.org/plugins/browse/blocks/)
• Create your own (CTA: create a block)
• Only the beginning (CTA: various resources)

Are you able to get started on an iteration with the above in mind and we can go from there? Here's a version below using this figma file that's quick and dirty:

[ndiego]

@marko-srb, no rush at all, but when you have a chance, can you provide a design update here? I hope to reference this on Thursday in my community update in the #website-redesign channel. Thanks! 🙏

[annezazu]

Noting for my future self that if/when /gutenberg is changed, we'll need to update the "try blocks live" link to go to a playground install OR perhaps have a playground block there: https://wordpress.org/plugins/interactive-code-block/ cc @adamziel in case you have some background insight on what would be most reliable.

[adamziel]

@annezazu Either of these options would work. What would be the goal of that showcase? To show WordPress core blocks? If so, either redirecting to Playground or embedding it directly on /gutenberg or /blocks via the WordPress Playground block would do the trick.

[marko-srb]

Hey hey,

I tried a few things that contain many of the perspectives/touch points discussed.

I am attaching the following:

1. Several different ways of visually (graphically) presenting blocks, while not going too far from the style what we have on our website.
2. I also tried to design several different flows of information (3 block page examples).

If any of these styles grab your attention as a good graphical representation of the blocks, please let me know.

—

Now, here is how the content flows on the page iterations:

What do you think?

[annezazu]

Thanks so much for this set of iterations! It's exciting to see some fresh designs. I liked the following sections, pulled from each. I think because some of the content isn't filled out, I had a hard time with others.

Notes: I love the way this shows content and clearly labels the block type. I think this is a dynamic and beautiful way to communicate what blocks are.

Notes: this feels very jazzy and in line with broader approaches on WPORG, again nicely emphasizing blocks and showing them as free flowing/interconnected.

Notes: I really like the gist of this visual but it's not quite there for me. I do think showing a block in the center then perhaps branching out to show the code side of it as you do and maybe what it might look like to extend it or have a variation of the same block would be neat. As is, it isn't quite there but I like the promise of the idea and think it could work nicely for a visual for devs who want to build with blocks.

As a reminder from this discussion:

He kindly clarified that /blocks is meant to be about how WordPress uses blocks, the block directory, and an introduction for developers who want to build with blocks.

To note what feels missing, I think we need a solid visual around the block directory.

[richtabor]

To be honest, I’m not confident any of these versions is much more compelling than what is currently live. The visuals are nice, but holistically I can’t tell who this is for.

Who is this page for? Developers who need convincing? People who don’t know what blocks are? Enterprise teams investigating the use of the Block Editor? Developers looking for block-related answers? I can’t tell from these explorations, nor the live version.

Dependent on that focus, the content structure should adapt. Perhaps it’s more block + code examples, like on Tailwind, that show a pattern with its block markup. Or an example of a block with its block.json file.

Or if we’re trying to convince someone to use blocks, we should clearly communicate the value of building, and using, blocks.

[annezazu]

Who is this page for? Developers who need convincing? People who don’t know what blocks are? Enterprise teams investigating the use of the Block Editor? Developers looking for block-related answers? I can’t tell from these explorations, nor the live version.

To answer this I'm going to pull from a separate thread on the /Gutenberg page:

"He kindly clarified that /blocks is meant to be about how WordPress uses blocks, the block directory, and an introduction for developers who want to build with blocks. In contrast, the /gutenberg page should be more about devrel, the architecture of gutenberg, and its use outside of just WordPress."

[SaxonF]

I find the layered approach most interesting which would include what the actual block looks like. The icon only tells part of the story as you might have custom blocks are more functional (like a form) or even animated in some way. https://www.radix-ui.com/ might provide some inspiration.

I’d also communicate that blocks can be style agnostic in that one block can be presented in many different ways depending on the theme/font/colour.

As for page structure, the original intent behind 2.2 was to present information in a way that aligns with how a user may interact with a block.

1. First they need to know what a block actually is. All your posts, pages and other content on your site are made up of blocks. A block may be as simple as an image or paragraph, or be interactive like a button or form. It represents a single element within a broader piece of content.
2. You then need to know what blocks are available to you. WordPress ships with a large collection of core blocks, but there are thousands of plugins that add all kinds of other blocks to your collection.
   You can also combine blocks to form what we call patterns. A pattern may only ever be included on one page, or it may be included in multiple pages and kept in sync across all. You can browse thousands of community made patterns, and even add your own for others to use.
3. If you’re a developer, you can create your own blocks. Blocks are essentially React components behind the scenes. You have full control over what the editing experience looks like in the editor, and what the front-end looks like once a page or post is published. Note: This deserves its own section including an actual code example as its one of the strongest ways we have to entice a new developer audience to WordPress.
4. To make use of blocks you can use the editor that’s built right into WordPress. The editor gives content creators a WYSIWYG interface that lets you drag and drop blocks into a page where they can adjust content and properties by clicking and typing. It’s a word editor on steroids and you can try it right now via this page (link to /gutenberg). Note: Important for us to not focus too much on the editing experience within the blocks page as we are talking primarily about the concept of blocks and not the editing experiences around them.
5. Best of all, blocks are not meant to be tied to any editor or even WordPress. If you want to move to another platform, they are designed to move with you. That’s what the open web is all about. You truly own your content.

[SaxonF]

I agree with @richtabor point. This conversation ties into the homepage discussion a little bit, and the general feeling that wordpress.org site feels quite fragmented and ambiguous at times.

"He kindly clarified that /blocks is meant to be about how WordPress uses blocks, the block directory, and an introduction for developers who want to build with blocks. In contrast, the /gutenberg page should be more about devrel, the architecture of gutenberg, and its use outside of just WordPress."

A missing piece there is the actual editing experience.

I'd personally like to see:

• A page that explains the concept of blocks whose goal it is to
  • Teach editors about what a block is which lays the foundation for teaching how they are used in WordPress, including a block based editor.
  • Attracts developers to WordPress, particularly the React/JS community who will resonate with the block way of working and the idea you can essentially drag and drop a React component into an editable canvas
  • Aligns the plugin community around an interoperable standard
• A page that focuses entirely on the editing/content creating experience which the blocks page can link to. This focuses on the "Design" and "Write" stages of the customer journey. This can include a live demo like the current /gutenberg page.
• A page or separate site that talks about Gutenberg as a block editor framework . This is the "Gutenberg as a platform" work that's ongoing but imo should not be tied to WordPress (e.g. https://tiptap.dev/).

[jasmussen]

Nice work. I quite like the reduction of a block into just a single rounded square with the icon, the same element even visually echoes some of the block editor, so it can be a strong branding element.

Reading through this, and echoing Saxon above, it’s very clear you’ve had to carefully manage multiple stakeholders and differing visions of what this page could and should be. To that end, I’d think there’s enough material here to work with to decide, what actually is the V2 of this page, before diving back into the work. So any visual feedback I have, I’d postpone to after that feedback has landed, it’s entirely possible it will be moot.

Some small things:

• The mostly light or mostly dark pages seem strongest to me. The homepage of the entire site can jump a big more in color between sections, but for a page telling a single story such as this, I’d theme the page to have one dominant BG color.
• The drop shadows could be unified across, those on blocks are top down and strong, those on screenshots are top left corner and soft.
• The pomegrade and green colors are not quite as impactful here. Something about this page feels more techy and could somehow invoke more synthetic colors.
• For the UI-screenshots, I’ve had good success re-building the UI in Figma so the screenshots can be fully tailored to the page itself, border radii etc, and I’m happy to help here if need be.
• The rotated block symbols feel less succesful to me, as they add an element of randomness that feels less intentional.

This is my favorite part of the whole thing:

The colors are maybe a tad pastel and we can refine the shadows, but there’s a spark here that combines the conceptual blocks with photography, typography, a “pattern”, very literally showing you able to compose artwork. I wonder, what would it look like if there was a range control or a toggle? Perhaps even a resize handle or focal point picker? Combined with beautiful typography and photography, the illustrations for the entire page could consist of abstract collages like this one, that show precisely how blocks with their associated design tools compose into patterns, ultimately into a page.

Nice work Marko.

[annezazu]

Thanks, all, for chiming in here! For larger changes, let's put that on pause until we can sync up with Matías. For now, I want to move forward with some light visual changes and an addition of a link to the block directory. I'll work with @jasmussen on this and follow up with a screenshot of the editor as we get closer.

[StevenDufresne]

I was looking at SEO the other day in a different context and it appears that users are still searching for "gutenberg blocks", not so much "blocks" or "WordPress blocks". Although I recognize we probably want to transition away from those keywords, it may be a good idea to include that language to meet users where they are.

Edit: This page doesn't return for those keywords.

[ndiego]

Yeah, "Gutenberg" isn't going anywhere 😅

[annezazu]

Here's a video of the iteration! Light changes in placement and design, a new more internationally focused patterns section (different languages), and an addition around 6.5/the latest to show off how things are actively being iterated upon:

blocks.iteration.mov

Big props to @jasmussen.