Create and test sample short descriptions

[wbamberg]

Write short descriptions for a small number (10) of CSS properties, and test how they would work in the different contexts they might appear in (an MDN page, an editor popup, a devtools widget).

On the basis of these samples:

1. draft some guidelines about how the short descriptions should be written
2. refine the estimates of how long it will take to update all of them.

[ddbeck]

Making a note here that the text will also need to serve as the seoSummary text on MDN, so it'll show up on search engine result pages too. Planning to consider that too

[ddbeck]

Thanks for your patience while I got back to you on this, @wbamberg.

Prior art

Before I actually did anything, I read up on how the existing page summary is meant to be used and searched kinda randomly for guidance on page summaries SEO purposes. I also took a look at search engine results pages (SERPs) for existing MDN pages, on Google, Bing, and DuckDuckGo. Then I started work on some mockups.

Mockups

To make the mockups, I started by picking out the 10 CSS properties. I tried to select properties that would cover CSS's full range, with a mix of new and old properties, well-supported and obsolete properties, shorthand and longhand properties, and so on. Here are the ten that I selected:

• background-position
• grid-template-rows
• border
• float
• flex-direction
• font-weight
• ime-mode
• border-top-color
• margin-block-start
• color

Starting with the last one, I made a very low-fidelity mockup of the first paragraph of an MDN page, a SERP, and a VS Code-style tooltip. You can see a gist of my mockups here (download the HTML file and open it in a browser—I promise it is extremely rudimentary). Then I proceeded to add and update the summaries for each, resulting in the full file.

Guidelines

After editing the properties, looking at them in the mockups (and sometimes editing some more), and the prior art, I came up with a handful of guidelines.

Note: I use the phrase "displayed characters" to mean the number of characters rendered by a browser, after parsing HTML tags like <strong> and <a>. The summaries as written in HTML will be longer, but this doesn't seem to have any impact on our use cases.

Constraints

• Summaries should be no more than 300 displayed characters. (Google's upper limit seems to be around this length, but it seems that Google chooses the length of page summaries by something other than a strict character count. Additionally, longer summaries look clunky as tooltips.)
• Summaries should be at least 100 displayed characters. (Shorter than this looks clipped or terse. There's also some SEO impact on this, with shorter summaries taking up less screen area and Google selecting other, longer text sometimes.)
• The first sentence should be no more than 150 displayed characters. (If the summary is truncated, especially on SERPs, then the summary still expresses a complete thought.)
• As previously discussed, the summaries should contain limited HTML (e.g., <a>, <em>, <strong>, and <code> tags only.)

Content

• Summaries should stand alone (since you won't know the context of the summary).
• Summaries should describe, in the active voice, what a CSS property does. "The some-property CSS property sets the …" is a good pattern for starting a property. (For several reasons, not least of which this seems to be rather common already.)
• Summaries should contain the name of the CSS property and the phrase "CSS property". (This makes it a little more clear what the tooltip was raised for.)
• Summaries should use the word "shorthand" if the property is a shorthand and (space permitting) name the related longhand properties. (Very handy in a tooltip setting.)
• Summaries may mention the name of a related shorthand property, if space permits. (Very handy in a tooltip setting.)
• Summaries may mention a property's status as obsolete or non-standard; summaries should not mention a property's other support status (e.g., experimental). (This is for maintainability.)
• Summaries should mention relevant keywords and topic areas (e.g., a property that affects layout should mention the word "layout" and perhaps the model in which it applies, such as "grid").
• Summaries should avoid the use of words like "specifies", "defines", or "determines" when the word "sets" is just as good and results in no loss of meaning.

Additional findings

It's very good news that most of these summaries didn't require major changes to get into shape. Most of the changes I made were to get the summaries' first sentence to fit into 150 displayed characters or to use less complex language (e.g., replacing "specifies" with "sets"). A few of the summaries required no changes. All of the pages had some kind of summary.

I expect that, with overheads like editing the wiki page or submitting a pull request, our previous estimate of up to 10 minutes per summary is right. Only one summary took more than 5 minutes to revise, but I also didn't really have any of the overheads (since I was just copying the inner HTML from the MDN pages' first paragraph into a file).

---

I think that's everything. Let me know if you have any questions. Thanks!

[wbamberg]

Thanks @ddbeck , this is really helpful. I'd love various people including @octref , @chrisdavidmills and @atopal to see this, and I also pinged the Discourse thread in case anyone watching that has any comments.

I think it's especially helpful to see the descriptions in context, and would encourage anyone reading your analysis to try out your mockups.

I think your recommendations are very sensible. Some topics for discussion:

• 300 is perhaps a little high. In conversation @octref wanted a max of 180. For some of the longer ones perhaps we could just use the first sentence? e.g.

The float CSS property places an element along the left or right side of its container, allowing text and inline elements to wrap around it. The element is removed from the normal flow of the web page, though still remaining a part of the flow (in contrast to absolute positioning).

• agree about excluding experimental. For many applications (including VS Code) browser-compat-data will also be queried so summary compat data can be provided. In that case this can be used to get support status. So perhaps the other support status items (deprecated, standard_track) could also be omitted from the short description?

• the point about shorthand is interesting, and makes me wonder if instead we should represent this in the data for the item: shorthandFor: ["text-decoration-line", "text-decoration-color", "text-decoration-style"]. Then an application could query that and display it in a consistent way.

[chrisdavidmills]

This looks pretty darn good to me, thanks @ddbeck ! I think most questions I may have had are answered by your write up. I did have some points to make about the actual content of the summaries, but I don't think these are relevant right now as well, so I'll leave those for later.

I agree with all of Will's comments.

I did have a point about title attributes being included with full summaries of properties linked to. They are shown to be problematic for accessibility in many ways, see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title#Accessibility_concerns. Do we need to include them?

[atopal]

Thank you Daniel, this is great! With Will's comments this sound really good to me. In particular, I'd leave out the non-standard/deprecated waring considering the space constraints. We already have that in mdn/data as part of the status field (although it's missing "deprecated" as an enum value).

[a2sheppy]

The <em> tag should be allowed in short descriptions as well, since we use it for certain types of emphasis.

[octref]

@ddbeck Thanks a lot for your work! Here are some of my input.

The float CSS property places an element along the left or right side of its container, allowing text and inline elements to wrap around it. The element is removed from the normal flow of the web page, though still remaining a part of the flow (in contrast to absolute positioning).

Same as @wbamberg suggested, the first sentence describes what float is, and that alone would be a good summary. The second sentence is useful, but a bit too specific as summary text.

Include support status (experimental / deprecated / obsolete)

I feel it's better to provide the metadata and leave this to the tool to decide. For example, I was playing around with this idea of showing emoji for experimental and deprecated properties:

https://twitter.com/octref/status/994649272309051392

the point about shorthand is interesting, and makes me wonder if instead we should represent this in the data for the item: shorthandFor: ["text-decoration-line", "text-decoration-color", "text-decoration-style"]. Then an application could query that and display it in a consistent way.

That would be great and could reduce the length of the summary too.

[wbamberg]

I did have a point about title attributes being included with full summaries of properties linked to. They are shown to be problematic for accessibility in many ways, see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title#Accessibility_concerns. Do we need to include them?

I'd be happy to exclude them (and there are some interesting resources linked from that section).

[ddbeck]

Thanks everyone for all of your feedback. I really appreciate the thought you've put into this. A few points to follow up on:

• I wrote my guidelines to be somewhat accommodating of existing summaries but I'm happy to have more constraints, like not mentioning support status at all or making summaries shorter. 👍
• I like the idea of having structured data for shorthand relationships. Should there be a separate issue for that, @wbamberg?
• I'd like to omit title attributes too, @chrisdavidmills. I find that they get in the way of editing the content that's actually displayed.

@wbamberg and I are going to have a discussion about next steps for this project. Stayed tuned!

[ddbeck]

OK, @wbamberg and I had a chat today about what needs to happen next. Here's what we talked about doing next

• Based on everyone's feedback, update the CSS property short descriptions page with revised guidelines based on everyone's feedback and an estimate for completing this project
• Open a PR to update the JSON schema and schema docs to add a short description field
• Write a script to check MDN page summaries against our guidelines/schema (to facilitate the next step; a proper linter for the summaries will eventually follow)
• Begin updating pages and mdn/data with summaries/short descriptions that fit the guidelines

I'll begin work on all this as soon as possible (though I'll be away for much of next week, so there's going to be a brief lull).

[octref]

I opened an issue to track integration in VS Code: microsoft/vscode#58391. Thanks again for making the data available!

[wbamberg]

Daniel's updated the main proposal (https://github.com/mdn/data/wiki/CSS-property-short-descriptions) with these guidelines and has provided some refined estimates in this issue, so let's close this piece.