diff --git a/text/0000-rust-bookshelf.md b/text/0000-rust-bookshelf.md new file mode 100644 index 00000000000..884dc499ee3 --- /dev/null +++ b/text/0000-rust-bookshelf.md @@ -0,0 +1,120 @@ +- Feature Name: N/A +- Start Date: 2016-12-25 +- RFC PR: +- Rust Issue: + +# Summary +[summary]: #summary + +Create a "Rust Bookshelf" of learning resources for Rust. + +* Pull the book out of tree into `rust-lang/book`, which holds the second + edition, currently. +* Pull the nomicon and the reference out of tree and convert them to mdBook. +* Pull the cargo docs out of tree and convert them to mdBook. +* Create a new "Nightly Book" in-tree. +* Provide a path forward for more long-form documentation to be maintained by + the project. + +This is largely about how doc.rust-lang.org is organized; today, it points to +the book, the reference, the nomicon, the error index, and the standard library +docs. This suggests unifying the first three into one thing. + +# Motivation +[motivation]: #motivation + +There are a few independent motivations for this RFC. + +* Separate repos for separate projects. +* Consistency between long-form docs. +* A clear place for unstable documentation, which is now needed for + stabilization. +* Better promoting good resources like the 'nomicon, which may not be as well + known as "the book" is. + +These will be discussed further in the detailed design. + +# Detailed design +[design]: #detailed-design + +Several new repositories will be made, one for each of: + +* The Rustinomicon ("the 'nomicon") +* The Cargo Book +* The Rust Reference Manual + +These would live under the `rust-lang` organization. + +They will all use mdBook to build. They will have their existing text re-worked +into the format; at first a simple conversion, then more major improvements. +Their current text will be removed from the main tree. + +The first edition of the book lives in-tree, but the second edition lives in +`rust-lang/book`. We'll remove the existing text from the tree and move it +into `rust-lang/book`. + +A new book will be created from the "Nightly Rust" section of the book. It will +be called "The Nightly Book," and will contain unstable documentation for both +rustc and Cargo, as well as material that will end up in the reference. This +came up when [trying to document RFC +1623](https://github.com/rust-lang/rust/pull/37928). We don't have a unified +way of handling unstable documentation. This will give it a place to develop, +and part of the stabilization process will be moving documentation from this +book into the other parts of the documentation. + +The nightly book will be organized around `#![feature]`s, so that you can look +up the documentation for each feature, as well as seeing which features +currently exist. + +The nightly book is in-tree so that it runs more often, as part of people's +normal test suite. This doesn't mean that the book won't run on every commit; +just that the out-of-tree books will run mostly in CI, whereas the nightly +book will run when developers do `x.py check`. This is similar to how, today, +Traivs runs a subset of the tests, but buildbot runs all of them. + +The landing page on doc.rust-lang.org will show off the full bookshelf, to let +people find the documenation they need. It will also link to their respective +repositories. + +Finally, this creates a path for more books in the future: "the FFI Book" would +be one example of a possibility for this kind of thing. The docs team will +develop critera for accepting a book as part of the official project. + +# How We Teach This +[how-we-teach-this]: #how-we-teach-this + +The landing page on doc.rust-lang.org will show off the full bookshelf, to let +people find the documenation they need. It will also link to their respective +repositories. + +# Drawbacks +[drawbacks]: #drawbacks + +A ton of smaller repos can make it harder to find what goes where. + +Removing work from `rust-lang/rust` means people aren't credited in release +notes any more. I will be opening a separate RFC to address this issue, it's +also an issue without this RFC being accepted. + +Operations are harder, but they have to change to support this use-case for +other reasons, so this does not add any extra burden. + +# Alternatives +[alternatives]: #alternatives + +Do nothing. + +Do only one part of this, instead of the whole thing. + +Move all of the "bookshelf" into one repository, rather than individual ones. +This would require a lot more label-wrangling, but might be easier. + +# Unresolved questions +[unresolved]: #unresolved-questions + +How should the first and second editions of the book live in the same +repository? + +What criteria should we use to accept new books? + +Should we adopt "learning Rust with too many Linked Lists"?