Questions about function summary and labels in specs and compatibility tables

MDN
#1

At https://groups.google.com/d/topic/mozilla.dev.mdc/vNDUwR1x71g/discussion there was a short discussion about questions regarding the spec. and compat. info.

I want to revive this discussion to turn its outcome into actionable items. Questions were:

  1. Should the summary of a CSS function or API include its parameters list?
  2. Is it ok to use something else than “Initial definition” in the specs list when the first specification defines a specific part of a feature? (in case of fit-content() this is "Defines the function when used as a track size.”)
  3. Is it ok to use something else than “Basic support” to describe the inital feature support? (in case of fit-content() this is "Supported as track size”.)

Answers I got so far from Sheppy and Chris say:

  1. Only when necessary for clarity, avoid bloating.
  2. “Initial definition” is useless, rather keep the column empty.
  3. Probably, but might cause scraper conflicts.

Regarding point 3, I wonder why the answer differs to point 2. “Basic support” is as useless as “Initial definition” without explanation what it covers. Somewhat related discussions:


“Initial definition” is at least an indicator for what’s the first spec., i.e. if you have to read the list from bottom to top or the other way round.

Sebastian

#2

We discussed a new name for “basic support” at one point. I believe it was “Available” or something like that; basically “yes, this identifier exists” without committing to how well it actually works at that level.

Sheppy

#3

My opinion:

“Initial definition” is fine. It’s more informative than nothing, and as you say, it indicates the order in which the table should be read.

“Basic support” is OK. I mean, it’s not ideal, but listing exactly what’s in there is not always practical, and choosing some other form of words is not going to make much difference.

I think “Basic support” makes more sense for some sorts of things than for others: especially, for something like a function, it indicates that there is a thing with that name you can call, then extra rows might add support for more arguments, say.

It’s more problematic in cases where a feature’s functionality is fully composed of a set of subfeatures, and you want the compat data to represent explicitly support for each subfeature.

For example, look at chrome_url_overrides: it’s an object which can have any of three named properties, each of which represents a bit of functionality. I want to represent support for each of these things separately, and I think that makes it easier to use than folding some lowest-common-denominator set of properties into “Basic support”. In cases like this, “Basic support” should IMO be omitted, because it doesn’t mean anything - it would be nonsensical to say we support chrome_url_overrides but don’t support any of its listed subfeatures. So part of the work @fscholz is doing now is to make it optional, so we can omit it in cases like this.

For something like CSS, too, we could perhaps imagine omitting “Basic support” and explicitly listing, for example, the different syntaxes that a property can accept, and the browser support for each syntax.