search

rust-lang / rfcs

RFCs for changes to Rust
https://rust-lang.github.io/rfcs/
Apache License 2.0
5.88k stars 1.56k forks source link

Documentation: documentation of unstable things #1819

Open steveklabnik opened 7 years ago

steveklabnik commented 7 years ago

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:

cxakpnxuuaeipwl jpg large

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

Thoughts?

And of course, anyone else 😄

GuillaumeGomez commented 7 years ago

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 commented 7 years ago

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

They do:

GuillaumeGomez commented 7 years ago

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

steveklabnik commented 7 years ago

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 commented 7 years ago

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

steveklabnik commented 7 years ago

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

llogiq commented 7 years ago

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:

This process itself should be thoroughly documented.

steveklabnik commented 7 years ago

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 commented 7 years ago

I'll try to write up an RFC soon

For the record, the RFC mentioned now exists: https://github.com/rust-lang/rfcs/pull/1828

chriskrycho commented 7 years ago

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 https://github.com/rust-lang/book/issues/478#issuecomment-282603595. :feeling slightly chagrined: