Decide how to render new specification section

[Elchi3]

I'm filing this issue to decide what we want to render (for now) in the new Specification section that gets data from mdn/browser-combat-data and w3c/browser-specs. See mdn/yari#3518 for the Yari implementation PR.

The idea is that authors provide a front matter

browser-compat: javascript.builtins.Array.pop

and a specification section

<h2 id="Specifications">Specifications</h2>
<p>{{Specifications}}</p>

and then a specification section is rendered automatically if data is provided in BCD and browser-specs. No manual HTML table anymore, no more SpecData.json editing in KumaScript.

In the past, this section has been a table. However, the feedback has been that it doesn't need to be a table necessarily. Given this section now becomes a component in Yari, we can render anything we like really. I'm trying to collect a few options here, so we can make up our minds. Proposals welcome. Note that we can always enhance this later so it would be good to agree on something that works for the start of rolling this out (maybe JS docs only for now).

Option 1

Try to be as close as possible to the current rendering. c.f:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toLocaleString#specifications
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toLocaleString#specifications

A feature with one specification:

A feature with two specifications:

A feature with no specifications:

[Elchi3]

Option 2

Switch to an unordered list. (Probably rename {{SpecificationTable}} to {{Specifications}} if we do this.)

Could be one line or two lines per spec (or something else, let me know)

[chrisdavidmills]

I feel like the table looks a bit neater, but maybe that's just because that's the look I'm used to?

One more point — the "A feature with no specifications:" warning box needs a heading, maybe "No specification found"?

[Elchi3]

One more point — the "A feature with no specifications:" warning box needs a heading, maybe "No specification found"?

Thanks Chris, that makes sense! I'll include it.

Option 3

Use a table but make it more rich by using data points the browser-specs data has to offer. (see the spec object for what's there). Example: Include links to spec repo and tests.

[Elchi3]

I think I'm leaning towards option 1 (which is a bit lame given it is what we have now), but for the moment it could at least help us test this new approach and then we could follow-up with a project to make the rendering more useful and better.

Thoughts? :)

[chrisdavidmills]

I think I'm leaning towards option 1 (which is a bit lame given it is what we have now), but for the moment it could at least help us test this new approach and then we could follow-up with a project to make the rendering more useful and better.

Thoughts? :)

I like it. We can then easily change the rendering if we want to improve it later on.

[dontcallmedom]

in https://github.com/w3c/webref/ we export data about extracted headings from browser-specs, so the currently cryptic #sec-array.prototype.tolocalestring could be replaced by the name of the section.

(it so happens that the extraction right now doesn't work correctly for the ecmascript spec, but that's just an easy fix away)

It would add a dependency of some sort to webref data, so this may bring more complexity.

in terms of layout, I think a one-column table is a bit of anti-pattern, so I would go with a list instead, but with better styling (closer to what option 1 looks like).

That being said, I think it would be neat to iterate on option 3 with more data to show - I'm not convinced "tests" is necessarily something most readers would understand or know how to use; and even "repository" maybe be hard to understand with people unfamiliar with how specs get written - but maybe a column pointing to where people can raise issue and bring feedback (which can easily be derived from the github repo) would be useful and actionable?

[Gregoor]

and a specification section

out of curiosity (and for my understanding): So we have pages with compat data but without specifications? Or converserly, if we do not, we could add these sections automatically?

[hamishwillee]

1. I like the table more than the list. It feels like a good way to insert "formal" information. So "1"
2. If compat data exists and specification exists in that, should yari auto-insert the spec data and heading even if these are not present?

[Elchi3]

Thanks for the feedback all! One thing seems clear: It can be a table or something else in the future, so in the implementation I changed the macro call to avoid the term "table". So, now you get the magic section when writing:

<h2 id="Specifications">Specifications</h2>
<p>{{Specifications}}</p>

[Elchi3]

in https://github.com/w3c/webref/ we export data about extracted headings from browser-specs, so the currently cryptic #sec-array.prototype.tolocalestring could be replaced by the name of the section.

(it so happens that the extraction right now doesn't work correctly for the ecmascript spec, but that's just an easy fix away)

This is really cool! Thanks for sharing. I'm excited to see there are even more possibilities with this approach.

It would add a dependency of some sort to webref data, so this may bring more complexity.

Right, I think I would like to get to this after the initial landing. We should probably have a follow-up issue to investigate integration of webref.

in terms of layout, I think a one-column table is a bit of anti-pattern, so I would go with a list instead, but with better styling (closer to what option 1 looks like).

Yes, I think we want something semantically correct, so a list seems preferable.

That being said, I think it would be neat to iterate on option 3 with more data to show - I'm not convinced "tests" is necessarily something most readers would understand or know how to use; and even "repository" maybe be hard to understand with people unfamiliar with how specs get written - but maybe a column pointing to where people can raise issue and bring feedback (which can easily be derived from the github repo) would be useful and actionable?

These are good points. I think calling it "Feedback" would be more actionable.

[Elchi3]

out of curiosity (and for my understanding): So we have pages with compat data but without specifications? Or converserly, if we do not, we could add these sections automatically?

• If compat data exists and specification exists in that, should yari auto-insert the spec data and heading even if these are not present?

I think in the future, we could auto-insert sections depending on the page type, but for now we haven't defined page types, so the idea is to rely on front matter and "markers" where to load BCD and Specifications sections.

--
browser-compat: javascript.builtins.Array.toLocaleString
--

...

<h2 id="Specifications">Specifications</h2>
<p>{{Specifications}}</p>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{Compat}}</p>

[Rumyra]

I'm very onboard with a link to the specification and one to give feedback. Agreed 'Repository' made need alteration, but given I've noticed issues coming through on MDN that are issues peeps have with specs and not MDN info, it would be really nice to have an easy way to point them in the right direction when the spec is the appropriate place.

[sideshowbarker]

That being said, I think it would be neat to iterate on option 3 with more data to show - I'm not convinced "tests" is necessarily something most readers would understand or know how to use

I think a tests link that went to https://wpt.fyi/results/css/css-color would be something that most developers would understand. It gives a visual representation of the tests results, from which developers could quickly get a sense of the state of how complete the support is for a particular feature in each browser — is it mostly green? or is there a lot of red?

That wouldn’t require them to know to use the tests — though if they open the link to a particular test case, e.g., https://wpt.fyi/results/css/css-color/system-color-compute.html, they’ll find a Run in your browser on wpt.live link they can optionally follow and use to run the test in their own browser and see the actual results in real time from running the test themselves.

So I think there’s quite big value to developers in having links to https://wpt.fyi/results in MDN. I think developers would love having it at point of use in MDN. It’s otherwise not something that’s readily discoverable to most developers. This would make it so.

[jpmedley]

I think you should start with option 1 and save the enhancements for later. (This is not a veiled argument against changing the spec sections. I have assumed all along there would be enhancements.) I'm not sure how easily conversion to the new macro can be automated. Option 1 lets you update the source at your own pace. Then when you introduce an improvement, it will be on the whole site instead of just the pages that have been updated. Joe Medley | Technical Writer, Chrome DevRel | ***@***.*** | 816-678-7195 *If an API's not documented it doesn't exist.*

…

On Fri, Apr 30, 2021 at 8:46 AM Michael[tm] Smith ***@***.***> wrote: That being said, I think it would be neat to iterate on option 3 with more data to show - I'm not convinced "tests" is necessarily something most readers would understand or know how to use I think a tests link that went to https://wpt.fyi/results/css/css-color would be something that most developers would understand. It gives a visual representation of the tests results, from which developers could quickly get a sense of the state of how complete the support is for a particular feature in each browser — is it mostly green? or is there a lot of red? That wouldn’t require them to know to use the tests — though if they open the link to a particular test case, e.g., https://wpt.fyi/results/css/css-color/system-color-compute.html, that will find a Run in your browser on wpt.live <http://wpt.live/css/css-color/system-color-compute.html> link which they can optionally follow and use to run the test in their own browser and see the actual results in real time from running the test themselves. So I think there’s quite big value to developers in having links to https://wpt.fyi/results in MDN. I think developers would love having it at point of use in MDN. It’s otherwise not something that’s readily discoverable to most developers. This would make it so. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <mdn/content#4482 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB6S7CZ6F2UVVNWEUJ7UTDDTLLGF3ANCNFSM43SU4PHQ> .

[Elchi3]

To give an update here: We'e went with option 1 for now and rolled this out to all reference pages under the JavaScript/ page tree. We will likely expand it to more sections of the site soon.
Iterating on the rendering of the specification section is not off the table, though. Feedback welcome on where to take this in a second phase.

[sideshowbarker]

I propose we migrate this to the Discussions tracker.