“Experimental” banners in API docs

MDN
#1

This regards the overuse of warning “This is an experimental API that should not be used in production code.” This is similar to June’s topic “Experimental” banners in CSS docs

My motivating example is found within page Element where we are told that clientTop and friends should not be used. This is way past astonishing. It is a shame, as it discredits all the other valuable information at MDN.

I can find mentions of clientTop on the web back before 2010, with references such as CSSOM and now CSSOM View Module. And in my bookshelf I find a mention in a book by Goodman from 2003. Hardly “nascent and immature”.

Unless fixing this particular example and all the others like it are somehow subsumed within the compatibility table project, I’d like to offer a simple suggestion. Any use of “{{experimental_inline}}” and the like, carried over from text more than, say, two years old should be summarily removed.

Unless of course you wish to temporarily clarify by replacing with a “{{we_have_no_idea_inline}}” macro. It really is that bad, this carrying over of grossly outdated misinformation for far too many years.

I do see the guidelines MDN conventions and definitions were updated only 4 months ago to describe proper usage of ‘experimental’. Perhaps this bruise on the MDN apple has previously been noticed?

BTW: The page for scrollTop says it is supported by everybody! How can it be marked ‘experimental’?

#2

Yes; we are in the process of phasing out that banner entirely. There are a couple of design discussions going on related to it, but generally you shouldn’t hesitate to remove that banner from pages covering well established APIs.

#3

Also, for what it’s worth, I should point out that there are thousands of pages on MDN, and it’s open to everyone to edit and update. That said, the bulk of the work is done by a small writing team, and we have to prioritize our time. Work on updating older documentation does happen, but we generally have to prioritize writing documentation for new technologies most of the time. Fixes like removing out of date banners tend to happen when we are coincidentally updating pages for other reasons.

That’s not ideal, but it’s the reality of the situation. I do definitely encourage anyone to feel free to contribute by updating things like this. Even minor fixes such as removing out of date banners or updating compatibility information are actually enormous wins for all MDN readers!

Sheppy

#4

Is there a way that we can aggregate pages in need of updates like this, so we can add this task to the Getting Started page?

#5

Actually, yes!

These may help. :slight_smile:

Sheppy

#6

Et voilà!
How and when to remove “experimental” macros

1 Like
#7

3 posts were split to a new topic: Macros and browser compatibility

#10

3 posts were split to a new topic: Docs and discussion for MDN macros