"Experimental" banners in CSS docs


#1

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 @sebastianzartner 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.

-webkit-animation

-webkit-transition

::backdrop

::grammar-error

::marker

::placeholder

::spelling-error

:any

:dir

:fullscreen

:has

:placeholder-shown

:scope

@document

animation

animation-delay

animation-direction

animation-duration

animation-fill-mode

animation-iteration-count

animation-name

animation-play-state

animation-timing-function

backdrop-filter

backface-visibility

bleed

block-size

border-block-end

border-block-end-color

border-block-end-style

border-block-end-width

border-block-start

border-block-start-color

border-block-start-style

border-block-start-width

border-inline-end

border-inline-end-color

border-inline-end-style

border-inline-end-width

border-inline-start

border-inline-start-color

border-inline-start-style

border-inline-start-width

box-decoration-break

box-suppress

calc

clip-path

contain

CSS_Animations

CSS_Display

CSS_Transforms

CSS_Transitions

CSSOM_View

display-inside

display-list

display-outside

element

fit-content

image-orientation

image-rendering

initial-letter

initial-letter-align

inline-size

line-break

margin-block-end

margin-block-start

margin-inline-end

margin-inline-start

marks

mask-clip

mask-composite

mask-image

mask-mode

mask-origin

mask-position

mask-repeat

mask-size

max-block-size

max-inline-size

min-block-size

min-inline-size

offset

offset-block-end

offset-block-start

offset-distance

offset-inline-end

offset-inline-start

offset-path

offset-rotate

overflow-x

overflow-y

padding-block-end

padding-block-start

padding-inline-end

padding-inline-start

perspective

perspective-origin

ruby-align

ruby-position

scroll-snap-type

tab-size

text-align-last

text-combine-upright

text-decoration-skip

text-orientation

text-size-adjust

transform

transform-box

transform-style

transition

transition-delay

transition-duration

transition-property

transition-timing-function

user-select

Using_CSS_variables

var


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.



“Experimental” banners in API docs
(Anthony Maton) #2

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 ?


(Chris Mills) #3

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.

As a result, I removed the banners.


(Stephanie Hobson) #4

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.

Stephanie.


#5

Thanks for the feedback. As a first proposal I’d like to remove {{SeeCompatTable}} from:

  • all the animation* properties.
  • all the transition* properties
  • transform
  • overflow-x and overflow-y

(sorry for the extra edit)


(SteveVS) #6

sort of new to MDN contributing, but I think you hit on a good subject…

and I totally agree with removing it from the animation properties since they have been around for years now. :slight_smile:


(erosman) #7

Some of the Experimental Technology became standard but the MDN wasn’t updated. (eg. ES6 implementations) :wink:


(Chris Mills) #8

Yup, this sounds good to me Will. Let me know if you want some help with doing it.


#9

Thanks Chris, but the updates are easy compared with the getting of consensus :).

I’ve updated the ones in here: https://discourse.mozilla-community.org/t/experimental-banners-in-css-docs/16864/5. Next step will be to do a more thorough run through all of them, to make a recommendation.


#10

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:

:scope
calc
overflow-x
overflow-y
perspective
text-align-last
text-combine-upright
text-decoration-skip
text-orientation (maybe not?)
var

This is really just a first proposal though, and I’d be happy to hear more views on it.


#11

I’ve updated the pages listed here: “Experimental” banners in CSS docs and updated the meta-documentation to recommend that people should use their judgement in applying this macro.

So I think this is closed for now.