I think the concern is not so much about the experimental namespace rather its prevalence in the official tutorials on tensorflow.org 18. And it’s a valid concern especially if you’re building educational resources that need a longer shelf life.
We don’t have an official editorial policy on this other than the content on tensorflow.org 18 represents TensorFlow “as it is”, meaning, the site docs should reflect the latest TF release (though we host older API reference versions and archive old docs). Notebook tutorials are executed and tested regularly to ensure everything works and the site is up-to-date, or at least doesn’t break. Most usage of experimental APIs in the TF docs are an improvement in API usability that, for whatever reason, failed to make the stable window. For an existing doc with an experimental API, you can always look through the docs version branches 6 to see how something was done before the experimental API was introduced.
Generally, if an experimental API is in an official tutorial there’s a strong chance a decision was made this is the best way forward. While tensorflow.org 18 has a lot of content and docs for many packages (some more stable than others), maybe we can be more thoughtful about how we introduce experimental APIs in the “core” guide 5 and tutorials 8 to make sure we provide a solid foundation for the larger TensorFlow ecosystem to build on.