Update the experimental spec warning banner to ask for feedback on the spec

[alispivak]

Think about improving the experimental spec warning banner to also ask for feedback. What would this look like? Also, think about how I'd like to see the feedback loop between MDN and specs, e.g. adding more examples back into the specs.

[alispivak]

Action item from January 2018 PAB meeting

[chrisdavidmills]

You can get a list of all pages that feature the {{SeeCompatTable}} macro (which generates the banner) at

https://developer.mozilla.org/en-US/search?locale=en-US&kumascript_macros=SeeCompatTable&topic=none

In terms of improving the banner to ask for feedback, could we modify the banner text to something like:

"This is an experimental technology
Check the Browser compatibility table carefully before using this in production. If you don't think this technology is experimental, leave a comment on our Discourse forum."

And then link the words "Discourse forum" tohttps://discourse.mozilla.org/c/mdn ?

In terms of feedback loop between MDN and specs, @dontcallmedom and I talked and I think we agreed that it would be good to start by writing a plan, and talking to a few spec owners and figuring out if they are OK with that plan.

I think the plan is very easy and simple, something like

We want better ties between specs and MDN docs. Specifically we'd like:

1. Real code examples added into specs where appropriate
2. A link to the canonical spec reference docs on MDN added into the top of the spec itself.

To action such requests, we would like to post issues or raise PRs on the appropriate spec repo.

Dom, who do you think would be best to talk to about this? Inside Mozilla, I could talk to:

• Marcos about Web Payments/Payment request
• Anne about DOM/WHATWG perspective
• David Baron or Tantek about specs in general

[dontcallmedom]

For sake of clarification, when we discussed this at the PAB, my idea of using it to ask for feedback was not so much for feedback on the "experimental" qualification, as much as for feedback on the spec itself - if a spec is experimental, it is almost certainly in need of developer input.

Otherwise, +1 on contacting Marcos and Anne; for specs in general, I plan to send a mail to our WG chairs list, so that may be a more direct path (but I have obviously no issue for you to also approach David and Tantek on the broader topic).

[chrisdavidmills]

Ah, I do apologise — now I get it ;-)

So the update to the experimental banner would be something more like:

"This is an experimental technology
Check the Browser compatibility table carefully before using this in production. If you have any feedback on this spec's design, file an issue on the spec repo."

Then link "file an issue on the spec repo" to the github issues page (or whatever link is most appropriate) for that spec. Does that sound OK?

I didn't realise you had a WG chairs list. I think that sounds like the most effective way to react out to the W3C for comment ;-)

[dontcallmedom]

"This is an experimental technology
Check the Browser compatibility table carefully before using this in production. If you have any feedback on this spec's design, file an issue on the spec repo."

Then link "file an issue on the spec repo" to the github issues page (or whatever link is most appropriate) for that spec. Does that sound OK?

Exactly what I had in mind; I can relatively easily document the relevant github repos in SpecData.json.

I didn't realise you had a WG chairs list. I think that sounds like the most effective way to react out to the W3C for comment ;-)

Right :) Although I expect a direct contact with specific people will have more impact, so I think we should pursue both in parallel.

[chrisdavidmills]

To share with MDN team (from @dontcallmedom ):

"Down the line, there are ongoing discussions about redesigning the set of links in W3C specs, and even broader discussion about redesigning W3C specs, which MDN should probably give input to in that context."

[chrisdavidmills]

This has now been shared with the MDN team for feedback too.

[chrisdavidmills]

So we had an interesting thread on this.

First of all, I was reminded that we were thinking of getting rid of banners like "experimental" and "deprecated", and instead looking at the browser compat data for the page and adding appropriate messages into the compat data section of the page if appropriate.

Everybody agreed that having a link back to the spec to provide feedback on the spec itself would be a good idea, but we were divided on where to put it.

Some members of the team think that it is good being at the top of the page in a banner, as it is easier to find there.

Other team members countered that that is too prominent a place for a link that most page readers won't be interested in, and that it should go in the Specifications section instead. Maybe in this 4th spec table column we've talked about.

I think the consensus is leaning towards the latter option.

As @schalkneethling said — "I reckon having a simple, not to in your face, UI item in the specification section of an element/feature would not be distracting. Nor do I believe it would cause a conflict of interest. The more web developers get involved with the standards process, the better I reckon. The various standards bodies are also hard at work in this regard so, if we can support them in some small way, I believe it is good for the web, and thus good for our users."

[chrisdavidmills]

As an update on this issue, I have implemented sample feedback guideance for the Web Bluetooth API:

https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API#Specifications

I've repurposed the "Comment" column, renaming it to "Feedback", as it is pointless in 99.9% of cases. Does this look OK?

Should we put this on every reference page of the API, or just landing and interface pages? What do we think?

[chrisdavidmills]

after further discussion, we decided:

• pick 5-10 specs to try this out on, to see what the real usefulness of this is.
• Also consider better way to generate these links, e.g. links in the SpecData file, and using a macro.

[alispivak]

@chrisdavidmills Can we close this?

[chrisdavidmills]

Not really. The experiment is not yet done.

[schalkneethling]

Not really. The experiment is not yet done.

Have we implemented anything for this?

[chrisdavidmills]

I think this can be closed at this point. The OWD is in the process of automating generation of the spec tables on MDN (see openwebdocs/project#24), and we are generally aiming to get rid of all experimental banners where we find them, as they are not helpful.