At the All-Hands in SF I sat down with Jen Simmons to get some feedback on our CSS docs. One of her comments was that we over-use the “This is an experimental technology” warning banner, that’s implemented using the {{SeeCompatTable}} macro.
We sometimes use it for technology that has quite stable cross-browser support and is quite unlikely to change in an incompatible way, even if its specification is not fully approved. Adding the banner is scary and unhelpful to people who could in fact happily use the technology, and may undermine our efforts to get it adopted. Also, overuse tends to obscure the cases where it is in fact warranted (a case of the docs crying wolf).
So: should we take a more relaxed approach to Experimental in the CSS docs? I’m tempted to have a fuzzier definition that asks people to use their judgement, and to suggest that if a technology has had a fairly stable implementation across multiple browsers for a while, we should not mark it as experimental, even if its specification status is draft.
A related issue is: instead of a big generic banner, maybe we could include a quick visual indication of the actual specification status of a technology, at the top of the page? We’ve talked about doing this for browser compat, perhaps we could crowbar it in there.
For reference, below I’ve listed all the pages under CSS that are marked experimental (I might have missed a couple). I’d be interested to hear if anyone wanted to argue that any of these should (or shouldn’t) have the {{SeeCompatTable}} macro removed.
Edited to add: I should have said to begin with: the current policy was probably a good one when a lot of these docs were originally put together a few years ago. But I think browser vendors have got better at working together, and changes in shipping implementations happen less often than they used to, so it’s worth considering an update to the policy to reflect that.
I agree with Jen if a technology is marked as experimental, I will never use it because I don’t want to come back to it in a few weeks / months.
If it’s nearly sure to be incorporated into the standard, I think we should remove the “Experimental”, maybe we could a note advising to pay extra attention to the compatibility tables if the feature is not yet standard ?
I agree with all this. FWIW, I was approached by a couple of devs at a conference earlier this year, who asked me why the Fetch docs have the experimental banner - they thought it was stable, it sounds scary, etc.
I agree we should scale back where we use the notice. I would be in favour of removing it entirely on pages where we have a browser compat summary at the top of the page.
We should make sure whatever is decided matches the work that @fscholz is doing on the browser-compat JSON.
I’ve taken a look through the remaining items in the list, and made a quick assessment of whether we should remove the “Experimental” banner. This is based on how good cross-browser support seems to be and whether it is prefixed or hidden behind a pref in browsers that do support it.
I’d suggest we remove the banner from the following: