CSS and class confusion: "summary" vs. "seoSummary"

MDN
#1

We have two classes with the word “summary” in their names. The first, located near the top of the style menu in MDN’s editor (unfortunately) is called “summary”. This class was added to support the now-defunct Zone system, and allowed marking a paragraph to be rendered in somewhat larger text, with some form of border. The first one on the page got pulled up and drawn in a special space in the zone’s header area. That’s all it was meant to be used for, really.

Unfortunately, people confuse it with the other class with “summary” in its name: “seoSummary”. This one is used to demarcate the page’s summary or description metadata, which is used in many ways:

  • When Google indexes the page, the “seoSummary” text is given to Google as the page description, and is therefore presented to users on search engine result pages.
  • MDN’s KumaScript macros that generate links, such as {{domxref}}, {{HTMLElement}}, {{cssxref}}, and {{jsxref}} use the SEO summary as the value of the link’s title attribute, thereby adding a tooltip to the link in most browsers.
  • Similarly, the sidebar generating macros, such as {{APIRef}} and {{ToolsSidebar}} use the SEO summary to add tooltips to the links they contain.
  • Macros that automatically construct menus and landing pages, such as {{LandingPageListSubpages}}, {{SubpagesWithTags}}, and {{SubpageMenuByCategories}}, use the SEO summary as the contents of the <dd> element in each <dt>/<dd> pairing.

Because of the similarities in the names of these classes, the fact that both are in the style menu, and the one that should be used exactly once on every single page is at the bottom of the style menu, we find pages being created using “Summary” rather than “SEO Summary”. We need to figure out a way to mitigate this problem.

The first and most obvious idea I had was simply to move the “SEO Summary” option in the style menu up to near the top, and the “Summary” one much farther down.

I also think we should rename the “Summary” option to something more like “Blurb” or “Featured Paragraph”.

Opinions, please?

Sheppy

2 Likes
Proposal - including CSS "short descriptions" in mdn/data
Should we omit title attributes from xref macro output?
Should we use `column-container` and `column-half` or `topicpage-table` and `section`?
#2

Yup, I agree with all of this basically. We need to resolve this confusion.

So, I would go for moving “seoSummary” up near the top, and changing the other class option to “intro”. I always used it for introductory paragraphs, some bits of which could also be used for the seoSummary.

2 Likes
#3

OK. I’ll file a bug to make that change. If I can spare a few minutes I may do that PR myself as it’s pretty trivial.

#4

Well… it would be trivial if the CKEditor style dropdown plugin didn’t insist on rearranging items on you. It insists on moving all block styles to the top and inline styles to the bottom, then sorting each group alphabetically. Annoying. I’m capable of arranging them myself, darnit. :slight_smile:

The change to the plugin that would be needed to let me arrange things at will is small; I just don’t know what the proper procedure is for establishing a custom version of a standard plugin. Hopefully @jwhitlock or @ryanjohnson can tell me. If it doesn’t take too much, I will sneak in a few minutes and do that. Otherwise, I’ll drop this and let it wind up on the dev team’s list, although I’d rather get it done sooner than I suspect they’re likely to be able to make time for it. :slight_smile:

#5

Is there a reason we can’t just remove the “Summary” option from the editor entirely, if we don’t want people to use it?

Going further, is there a reason we can’t also remove the special styling for class="summary"?

1 Like
#6

Those are good points. I personally think that’s a good idea. I don’t think we need this; it’s tending to get used more to do a call-out type of ‘Hey, this is an especially interesting but not “note”-worthy bit of text’ kind of thing rather than for summaries per se.

Anyone else have opinions on that notion? I think I might amend this proposal to "Remove the current summary option from the menu and rename “SEO Summary” to just “Summary”, and then also remove the special styling from the “summary” class so it doesn’t stand out anymore.

We can then optionally consider adding a new “hero text” class of some kind, which might not be a bad idea, but that would be a separate issue.

Sheppy

1 Like
#7

I really like having a style for “Intro” or whatever, I think it looks good to highlight the introduction, or the abstract, or whatever…

…saying that, it is not used consistently, so it mainly serves to over complicate the documentation procedure and make the site less consistent. For these reasons, I would be in favour of getting rid of it.

1 Like
#8

I don’t have an objection to the notion of an “Abstract” or “Intro” style, we just need to separate it thoroughly enough from the concept of “Summary” to avoid confusion, then document and enforce the processes so they’re both used properly.

1 Like
#9

I’m in favour of renaming “Summary” to “Intro(duction)”, because when both are used correctly, it improves the look and organisation of the page.

Examples:

#10

I can handle that. I’m tempted to suggest we think of another name for it, just because it could hypothetically be used in places other than just the beginning of an article. Maybe “Abstract” or something?

#11

I believe that “Intro” can work for that too, as it can be used to introduce a section as well.

#12

@hellosct1 incorrectly removed the summary and seoSummary classes from https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions, so I reverted the change.

#13

Personally I think pages with fewer style changes are cleaner and easier to read. I feel the same way about our overuse of Note and Warning boxes, they sometimes give our docs a “million dollar homepage” feel.

So you could say that I’m not very keen on the “summary” style. But I’m not very dogmatic about this, and could see it might be good if applied properly.

But:

…saying that, it is not used consistently, so it mainly serves to over complicate the documentation procedure and make the site less consistent.

To me this is really key. We can discuss whether we’d like to have a highlighted “intro” section, and even, if we get bogged down in opinions, perhaps user test whether it’s effective. We can discuss also whether it’s better in some pages (e.g. guides) than others (e.g. reference) and how it should sit with other design elements of the page (e.g. interactive examples or summary compat tables).

But we should have a consensus on what we want to do here, for which pages, and how we will get it done before charging ahead. For example, if we want it for all the JS guide pages, we should enumerate these pages and track the work to add it, and drive it to completion.

Otherwise we’ll just end up with a mishmash.

2 Likes
#14

To close this (at least for now) shall I:

  • file a Kuma issue (or PR) to remove the special styling from “summary”
  • update the page templates to remove the “summary” class

? It seems like we more or less had consensus on this, in this thread.

#15

Please do, yes. Thanks Will, I think this is for the best.

#16

The CKEditor toolbar needs to be updated as well.

1 Like
#17

Submitted Kuma PR 5154 (https://github.com/mozilla/kuma/pull/5154) to remove the “Summary” item and rename “SEO Summary”.