Documentation: documentation of unstable things

[steveklabnik]

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 Document RFC 1623: static lifetime elision. rust#37928 )

And of course, anyone else 😄

[GuillaumeGomez]

The thing is: unstable docs don't show up in stable ones. So I'm not sure to fully understand what the meaning of this is. I'm not against a few precisions. :)

[steveklabnik]

The thing is: unstable docs don't show up in stable ones.

They do:

• https://doc.rust-lang.org/stable/book/nightly-rust.html
• https://doc.rust-lang.org/stable/std/intrinsics/index.html

[GuillaumeGomez]

Ok, now all this makes sense. Shouldn't we just remove unstable docs from stable ones?

[steveklabnik]

Part of the motivation here is discovery; if we don't have people at least seeing what's coming up in new releases, we get even less feedback about them.

[GuillaumeGomez]

If they're looking to stable docs, I assume they have a stable rustc, so they can't use it, right?

[steveklabnik]

Yes, but the idea is that it often goes something like this:

• I need a function that does X. Let me look at the docs.
• Oh hey look, here's a function that does what I need, but it's not yet stable.
• Let me click the link and say "hey, I really need this" on the associated github issue.

[llogiq]

Most people who run nightly will also have a stable Rust lying around, thanks to multirust. I actually have stable, beta and nightly on my machine, because I like to benchmark all of them e.g. for bytecount. Coming from another angle, many folks I know use stable, but have a nightly lying around for clippy.

I think making unstable features discoverable in stable docs can't hurt and certainly improves discoverability, so let's keep it that way. A disclaimer that the described features are "in active development and can change at every time" would be appreciated.

Regarding process, I suggest every feature tracking issue be closed with a PR that:

• moves the documentation from "nightly rust" to its proper place, cleaning it up if required
• removes the feature gate and code needed only for the feature gate (this includes removing the #[feature(..)] annotations from doctests)
• adds a short introductory text to a "features introduced in this release cycle" document that should be live on the site

This process itself should be thoroughly documented.

[steveklabnik]

I spoke with @brson today about some documentation-related infrastructure issues, and I believe I have some answers here. I'll try to write up an RFC soon; the holidays make it tough.

[frewsxcv]

I'll try to write up an RFC soon

For the record, the RFC mentioned now exists: #1828

[chriskrycho]

I missed this in the end-of-year blitz in offline life; looking at this and the (merged!) RFC now in light of a comment on rust-lang/book#478 (comment). :feeling slightly chagrined: