Feature definition guidelines

[foolip]

We should have detailed guidelines and principles for how to create feature groups in https://github.com/web-platform-dx/web-features/tree/main/docs.

Known discussions:

• Naming conventions #24
• Editorial overrides: consider marking non-essential parts of a feature #485
• Baseline status for single features vs aggregated group status #495
• Guideline for event constructors #504
• Guidelines for short names #548

[foolip]

The main questions to resolve:

• How do we handle "non-critical behavioral sub feature"?
• How do we handle features that arrive in bits in pieces, possibly many individual launches over time? Should we somehow mark the critical (constitutional) parts, or the non-critical parts?
• What's the role of subgroups in the above?

[captainbrosset]

At the last WebDX CG meeting, I volunteered to create a shared doc to list the current discussions and questions to resolve. The idea is that, over time, this document would morph into a series of guidelines for how to create groups.

[captainbrosset]

I started unearthing relevant discussions from GitHub and moving them to this shared document: https://docs.google.com/document/d/1Y2hTj9IqgLxOXmlePKttA0muB47DCI5tkeIIevmc18M/edit?usp=sharing

Please add to it if you know of others.
Please also comment so we can move this document forward and help it become a set of guidelines we can use going forward.

[tidoust]

Additional questions and conventions that could perhaps be worth addressing in the guidelines:

• What makes a good feature group? The README says that "web-features identifies, defines, and categorizes capabilities of the web platform that web developers care about". Can we expand on that a bit to create a slightly more actionable list of checkpoints when we consider a feature group for inclusion?
• What are the recommended fields in the YAML file when the feature group is created? The schema only requires the spec field. Should the caniuse and/or compat_features fields be set upon creation, when possible? The usage_stats field? The human-friendly name, when it exists (see Feature Request: Human Friendly Name for Feature Definitions #490)?
• What should the spec field contain? The code currently asserts that the URL maps to a nightly URL in web-specs. More generally, human-friendly documentation about the YAML schema would ease contributions and reviews. That could be done in a separate document, linked from a guidelines doc.

[foolip]

We need guidelines for the situation in #546.

[ddbeck]

I started unearthing relevant discussions from GitHub and moving them to this shared document: https://docs.google.com/document/d/1Y2hTj9IqgLxOXmlePKttA0muB47DCI5tkeIIevmc18M/edit?usp=sharing

Please add to it if you know of others. Please also comment so we can move this document forward and help it become a set of guidelines we can use going forward.

This is great. @captainbrosset has done a bunch of good work here. I was thinking of how to start to get this stuff formalized. I thought a template might help, something along these lines:

• Heading: Short, declarative direction
• Description of the rule/guideline
• Good example(s)
• Bad examples
• A list of issues and PRs where the guideline was discussed

## Don't use foo and bar feature descriptions

Metasyntactic variables aren't very memorable. Use real examples.

Incorrect examples:

- ~~The function accepts a string ("foo") and returns a length (3).~~

Correct examples:

- The function accepts a string ("Esperanto") and returns a length (9).

Issues, PRs, and related guidelines

- #10000
- #10001

Then as we get close to consensus, we could fill in the template and open a PR for each guideline. It might also help us break up larger guidelines into smaller ones, to make the reviewing/editing work easier to do.

[foolip]

As I've written a bunch of descriptions and discussed with @ddbeck in PRs, a pattern is emerging, which is "The X does Y" in the active voice. Sometimes I've added a second sentence to gesture at common uses. Descriptions I'm happy with so far:

• The appearance CSS property controls the appearance of form controls. Using appearance: none disables any default native appearance and allows the elements to be styled with CSS.
• The aspect-ratio CSS property controls the width-to-height ratio of elements. For <img> and <video> elements, the width and height attributes used together with height: auto control the aspect ratio while the image/video is loading.
• The :autofill pseudo-class matches <input> elements that have been filled in automatically by the browser.
• The CSS cap unit corresponds to the height of Latin capital letters.
• The color-mix() function mixes two colors in a given color space and by a given amount. Commonly, lighter or darker variations of a color are created by mixing with white or black.
• The CSSStyleSheet constructor creates a new stylesheet which can be shared between a document and multiple shadow roots using adoptedStyleSheets.
• The shadowrootmode attribute on <template> creates a shadow root without the use of JavaScript. It is a declarative alternative to the attachShadow() method.
• The fastSeek() method seeks an <audio> or <video> element as fast as possible, by seeking to a keyframe instead of exactly the requested time.
• The input event fires when a form control changes or an element with the contenteditable attribute changes.
• The CSS lh unit corresponds to the requested line height, the computed value of the line-height property. Some lines may be higher than this based on their content.
• The linear() easing function for animations and transitions interpolates linearly between the control points, and can be used to approximate complex easing functions, for example a bounce effect.
• The Promise.allSettled() static method waits for an array of promises to settle (resolve or reject).
• The text-spacing-trim CSS property controls spacing around CJK characters, avoiding excessive whitespace when using full-width punctuation characters.

I've been inconsistent about when "CSS" is used and would like to fix that, generally by removing it.

Descriptions that don't fit this style:

• Array and Promise descriptions (through no fault of @Elchi3, I approved the PRs without suggesting anything)
• Transform elements with separate translate, rotate, and scale CSS properties.
• Provides access to raw mouse movement by locking the target of mouse events to a single element and hiding the mouse cursor.
• WebVTT is a captions and subtitles format. WebVTT files are loaded using the <track> element, and the VTTCue API can be used to create or update cues dynamically.

Finally there's "A promise represents an asynchronous operation which eventually succeeds or fails" which is in the active voice but is just "An asynchronous operation which eventually succeeds or fails" with extra fluff.

Now, discuss!

[foolip]

A few observations...

Repeating the name of the feature often helps make clear what it is. The description "The linear() easing function for animations and transitions interpolates linearly between the control points, and can be used to approximate complex easing functions, for example a bounce effect." would be worse as "Interpolates linearly between the control points, and can be used to approximate complex easing functions, for example a bounce effect." This is an extreme case, but I think it's helpful to say "property", "element", etc.

I'm not sure if descriptions need to make sense in isolation, or if we should assume some context in the presentation. In particular, if we can assume that all features grouped as CSS are somehow identified as such when presented, then we can be more comfortable with a description like "The cap unit corresponds to the height of Latin capital letters."

In a few cases, "X is Y" seems more natural than "X does Y", and we probably shouldn't create tortured prose to fit all descriptions into the same format. The WebVTT description seems just fine to me, for example.

[ddbeck]

I was giving some thought to the "X does Y"/"X is Y" and "Does Y" distinction. What would these look like in different contexts? For example, as part of some partly generated feature docs (e.g., like an MDN reference page where there's a title usually immediately followed by some text reiterating the title) or as a tooltip.

I did a bit of poking around to see what high-profile webdev docs are doing (e.g., Tailwind, React, etc.) and a random exploration of code tooltips in my editor.

The main things I learned:

• There's no obvious convention. We can choose any reasonable option and not end up anywhere weird.
• We should worry most about avoiding repetition between features, not between the feature name and the feature description. Seeing "Utility for…" over and over is not helpful and does not aid skimming or understanding. Thus we should prefer things like "some-prop property sets…" over "The property some-prop sets…", since the distinctive thing will be first.

As for "X does Y"/"X is Y" and "Does Y", my conclusion is that it probably doesn't actually matter. That said, I think "X does Y" has a slight edge, given two points:

• The repetition makes reuse slightly safer (e.g., you can use a description as a tooltip even if the thing you're mousing over doesn't contain the title: see this non-functional link), as you don't need to depend on a specific context for the description to make sense.
• It's easier to review and edit a complete sentence than a fragment.

[foolip]

doesn't actually matter

I think this is a fair summary. Let's write down "X does Y" as our guideline, but with a big "or whatever you like" exception. I think everything will turn out reasonable just through copy-pasting existing descriptions to make new ones.

[captainbrosset]

Because I write technical documentation a fair amount of my time, I do have a few strong opinions about this:

• The description should make sense on its own. We shouldn't assume that it will be displayed in combination with the feature name. "This X does Y" is much better than "Does Y".
• We should use the active voice whenever we can. The subject of the sentence (the feature) performs the action. It's more concise and easier to understand by all.
• Using "The X CSS property", or "The Y method" (or similar) is useful for setting the context since the feature name doesn't have this context. I would therefore prefer "The X thing does Y" (where thing specifies the nature of X) over "X does Y".
• We should keep the description as short as we can to avoid them turning into technical documentation over time. It's highly likely that web-features will be almost always be displayed in conjunction with MDN (or other) docs.

[foolip]

@captainbrosset thank you! It sounds like the descriptions we've written so far mostly aligns with your opinions. Do you think they should be shorter in general though?

[ddbeck]

• We should keep the description as short as we can to avoid them turning into technical documentation over time. It's highly likely that web-features will be almost always be displayed in conjunction with MDN (or other) docs.

I'd propose starting by setting an arbitrary character limit—we'll probably figure out pretty quickly if we're trying to stuff too much into the description. Maybe a tweetspan, 280 characters?

[foolip]

280 works. The longest we have now is 244.

[atopal]

• We should keep the description as short as we can to avoid them turning into technical documentation over time. It's highly likely that web-features will be almost always be displayed in conjunction with MDN (or other) docs.

I agree with the point that this should not be turned into technical documentation over time and a character limit seems a good way to achieve that, but I don't think the assumption above will hold (see for example https://caniuse.com/flexbox-gap where this would be a perfect fit). I don't think it changes anything about the guidelines so far, just wanted to state that for possible future guidelines.

[foolip]

https://caniuse.com/flexbox-gap has a very short description, what assumptions do you have in mind there?

[atopal]

That there are no docs to provide context like there is on an MDN page.

[foolip]

So I guess you're saying that description is too short? Maybe we need a minimum description length too? 😆

[atopal]

No, I just linked to that random caniuse.com page to illustrate that there are places where the short descriptions will be used without any other documentation on the page, so we should keep that in mind and never assume that there will be more context for the short description.

[foolip]

Ah. I agree, the descriptions should stand on their own, and only assume the short name is also shown. Most of them would work without the short name too.

[ddbeck]

Description guidelines came up in the WebDX call today. I opened #789 to capture as much as I could of the description reviews/edits so far.