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).
Our metadocs for CSS say this: “A property is not experimental if it is on the standard track (that is, in an official spec), its spec is a Candidate Recommendation, a Proposed Recommendation, or a Recommendation, and it is not listed as a feature at risk in it.”.
Afterwards I discussed this with @sebastianz and @fscholz. It emerged that Florian uses a less conservative approach in the JS docs, only using the banner for genuinely experimental technology, like SIMD. The JS metadoc I found for this says The Experimental tag should only be used with new features where the standard in not yet finalized (e.g. in a strawman proposal) and the feature is in a Nightly version or behind a preference.
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.
