Re: Questions about function summary and labels in specs and compatibility tables

[Eric Shepherd]

> On Feb 16, 2017, at 6:27 AM, Sebastian Zartner <sebastia...@gmail.com> wrote:
>
> 1. Should the summary of a CSS function or API include its parameters list?

IMO, not unless there’s something special about a parameter that justifies calling attention to it, or the parameter is so important that not having it makes the summary unhelpful. But a lot of the time, just knowing “Defines amount of rounding applied to a box’s borders” or something like that is all you need to know. The details aren’t as important as quickly knowing “this is the property I need."

> 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.”)

Definitely. Personally, I think “Initial definition” is useless and shouldn’t be used at all. It means nothing, really.

> 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”.)

That’s a good question. I think so, but it may depend on what’s being done with scrapers and stuff that rely on our tables.


Eric Shepherd
Senior Technical Writer
Mozilla Developer Network <https://developer.mozilla.org/>
Blog: https://www.bitstampede.com/
Twitter: https://twitter.com/sheppy

[Chris Mills]

> On 27 Feb 2017, at 22:26, Eric Shepherd <eshe...@mozilla.com> wrote:
>
>
>> On Feb 16, 2017, at 6:27 AM, Sebastian Zartner <sebastia...@gmail.com> wrote:
>>
>> 1. Should the summary of a CSS function or API include its parameters list?
>

> IMO, not unless there’s something special about a parameter that justifies calling attention to it, or the parameter is so important that not having it makes the summary unhelpful. But a lot of the time, just knowing “Defines amount of rounding applied to a box’s borders” or something like that is all you need to know. The details aren’t as important as quickly knowing “this is the property I need.”

I’d agree with this. + Including too many details on the landing page of an API interface can bloat it rather.

>
>> 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.”)
>
> Definitely. Personally, I think “Initial definition” is useless and shouldn’t be used at all. It means nothing, really.

Yeah, we might as well not include anything at all in that column, unless there is a spacial case that is worth mentioning.

>
>> 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”.)
>
> That’s a good question. I think so, but it may depend on what’s being done with scrapers and stuff that rely on our tables.

Yup, need to check that out.