Documentation: documentation of unstable things

RFC 1636 is wonderful, but its first attempt at being followed has brought up an interesting procedural issue, which has brought up a broader weakness in our documentation strategy, and that's documentation of unstable things.

Historically, we've taken this strategy:

1. Prioritize documenting stable things over unstable things.
2. API docs have a stability marker placed next to them, so it's clear what's stable and what's not.
3. The book has a section on "Nightly Rust", which is for long-form documentation for unstable things.

That's it. But RFC 1636 will involve lots of things landing in the reference, which has no capacity for stable vs. unstable things. And nightly Rust, while it's in a section titled that, doesn't necessarily do a good job of showing that stuff is nightly only.

So this question is this: how do we plan on tackling this problem?

My first instinct is to have some kind of "aside" box, like you might see in other kinds of docs. Here's the W3C:

This would work, but then it's unclear that, when removing the gate, this stuff will be updated.

Thoughts?

• @rust-lang/docs (obvious reasons)
• @rust-lang/tools (since Rustdoc may need to grow something for this)
• @rust-lang/compiler (since they'll be the ones generally implementing the "make this stable" PRs)
• @chriskrycho (who wrote the original RFC)
• @llogiq (who commented on https://github.com/rust-lang/rust/pull/37928 )

And of course, anyone else 😄

Start by reading RFC 1636 and the linked PR 37928, then review how the Reference and the "Nightly Rust" section currently identify unstable features. The work is complete when the project has an agreed, maintainable strategy for marking unstable documentation and keeping it updated as features stabilize.