search

mdn / pab

MDN Web Docs Product Advisory Board
26 stars 17 forks source link

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

Closed alispivak closed 3 years ago

alispivak commented 6 years ago

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 commented 6 years ago

Action item from January 2018 PAB meeting

chrisdavidmills commented 6 years ago

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:

dontcallmedom commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

"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 commented 6 years ago

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 commented 6 years ago

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

chrisdavidmills commented 6 years ago

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 commented 5 years ago

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 commented 5 years ago

after further discussion, we decided:

alispivak commented 5 years ago

@chrisdavidmills Can we close this?

chrisdavidmills commented 5 years ago

Not really. The experiment is not yet done.

schalkneethling commented 5 years ago

Not really. The experiment is not yet done.

Have we implemented anything for this?

chrisdavidmills commented 3 years ago

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 https://github.com/openwebdocs/project/issues/24), and we are generally aiming to get rid of all experimental banners where we find them, as they are not helpful.