Update Heading Block description

[0aveRyan]

The current description for Heading blocks confusingly states that Headings are placed above the post or page contents, when they're used to describe document sections.

• Headings divide the page contents, aren't placed above.
• Headings may be used in CPTs -- direct reference to Post or Page should be removed.
• Headings vs. Subheadings -- one is used for SEO weighting, one is simply formatted paragraph text... we don't want to get overly technical, but this distinct difference should be gently explained.

[michelleweber]

Could you share screenshots of the things you think should be changed? And do you have proposed language (it's fine if you don't)? Thanks!

[0aveRyan]

@michelleweber
This is the description that prompted this PR:

These headings are used inside the page content to divide it, not above it.

This description is also not super clear:

Updated Heading description:

Updated Subheading description:

[michelleweber]

Perfect, thanks. I'll offer tweaks that you can take or leave; your suggested changes are clear, but I'd love to bring the tone more in line with the other descriptions.

Heading: Help visitors (and search engines!) understand what they're reading with a short description.

I still like the subhead description, but if you want something more pointed:

Subheading: Add a subtitle above a section of your content to introduce your next topic and help readers follow the flow.

(Personally, I'm not sure the user needs to know at this point that the heading is used for SEO, I think they just need to know what happens when they insert this block. So my instinct would be either to save the space and remove that, or include it as a parenthetical to make it clear that it's supplemental info.)

[chrisvanpatten]

One note about the subheading block is that it can only be used once (see #8140).

[0aveRyan]

@chrisvanpatten yeah.. that's really not apparent, I think #8140 needs reopened. As indicated in that PR and in the audit in #8234 (which suggests killing it), it's super confusing when to use it.

Also, it seems strange that a Subheading is simply a <p> tag with a targetable classname. If it stays, there should be a way to set this to a true semantic heading tag, but that makes it all the more confusing.

I appreciate the value, I've built plenty of news sites with those subheading decks, but without a way to really explain itself easily and the nuance between it and say an <h3> it seems likely it would often be used incorrectly as the review indicated.

[chrisvanpatten]

Also, it seems strange that a Subheading is simply a

tag with a targetable classname. If it stays, there should be a way to set this to a true semantic heading tag, but that makes it all the more confusing.

It's not semantically a heading though :)

But yes I agree about reopening #8140 and totally appreciate the confusing name.

[0aveRyan]

Yes, the envisioned use isn't a semantic <hX> tag, but if left-in, making it a semantic heading seems only fair to the developers who would rightly assume a Subheading is a form of semantic heading.

As subtitle or deck it's much less confusing. It's totally reasonable to assume Subheading would refer to some form of <h2> - <h6>.

[0aveRyan]

For this PR, I've reverted changes to the Subheading block to make the correction to the Heading block only @michelleweber, however the new description doesn't really speak to section-ing the document and kinda sounds like an excerpt.

[ZebulanStanphill]

Briefly describes the following section to visitors and search engines.

Help visitors (and search engines!) understand what they're reading with a short description.

I do not either of these descriptions work. It sounds like some kind of meta description. A heading is definitely not a short description of the content that follows. It is the title of a section of a document... or in other words, the heading of a section of a document.

How about something like this:

Use a heading to add a title to a section of content.

Or alternatively:

Add a title to a section of content with a heading.

Or how about this:

Use headings to divide your content into named sections.

[michelleweber]

Heading: Help visitors (and search engines!) understand what they're reading. Add headlines to introduce your topics and help readers follow the flow.

And for subhead, the original subhead text plus "Use it under a heading to add context." for more clarity.

[0aveRyan]

@michelleweber thank you for your patience 😌 I think these are getting nicely refined.

If I may be a bit picky, Headings could be used to title Video/Embed blocks, Audio/Playlist blocks, etc, so I'm not sure about reading and readers. How do you feel about Introduce topics and help visitors (and search engines!) understand how your content is organized.?

I hesitate to update the Subheading in this PR if #8140 is being reopened as @chrisvanpatten indicated, so that can be a separate PR. As-coded, the block can only be inserted once, intending to be used as the first block in the_content, however can be inserted elsewhere and there's a plugin to allow infinite copies of it... I think as-named it's a bit confusing and the independent block audit suggested removing it. If it does stay, I think it's single-use limitation would need to be conveyed in the description.

[michelleweber]

@0aveRyan, that sounds just fine to me!

[karmatosed]

Thanks for this everyone, looks great and I agree let's focus on heading as depending on the issue, subheading may not be around long.