Rust 2019 and beyond: limits to some growth

So whatever Wirth has done was quite of interesting in terms of language research for the language geeks among us, but hardly with any market relevance.

For example, I don't think that every last detail of #[repr(...)] needs to be covered in the Book; but as the entry point for most people, it's how they discover features, so it should at least provide an introduction, and link to the reference for more information.

Likewise, while I think that the std::ops documentation does a good job of covering all of the details of operator overloading, I think the Book could provide a slightly more discoverable introduction to operator overloading which isn't just being used as an example of another feature, default generic type parameters, and provide some links to std::ops which might help with the Googleability problem.

One thing that I think really needs to be focused on is some SEO for the docs. For some reason, the way the Rust docs have been organized over the years, with old versions of docs and the old book being replaced by the new one, means that a lot of times, when I search for something I find old, out of date docs.

For instance, with operator overloading, if I search for "rust operator overloading", I find Rust by Example, which is OK but has a lot of text in comments which is harder to read, followed by a first edition link which warns about being out of date and then provides a link to the new book but not where in it to look, as well as a link to the 1.30.0 version of the first edition book, then a link to std::ops (which if I were a newcomer, I might not realize was relevant), then a 1.5.0 edition of the book.

The first edition operator overloading chapter seems pretty reasonable, actually, and it's present in the table of contents so its more discoverable, and it contains a link to `std::ops`. But because of the new structure of the second edition book, the first page I see if I try to check the book tells me that it's outdated, and directs me to the new book in which this material is harder to find.

And in the new book, even once I find it, there's not much to direct me to where to learn more about the topic. There's no link to `std::ops` documentation; I have to separately look that up.

Part of the problem was that the first edition book was a bit more like a more accessible reference, while the second edition has a more narrative or tutorial structure. So there's no longer a place to go for an accessible reference to all of the language features. There's the Reference, but that's written for detail and precision and not accessibility, and as discussed, is incomplete. There's Rust by Example, but that's mostly just code examples with commentary in comments. The second edition book covers a lot of the same material as the first edition, but because of the different structure, some of the "reference information" on more advanced features is just buried in a couple of "Advanced X" chapters.

I'm not sure of the best way to address this; I admit that getting this right isn't easy.

One option might be to have the new book be in two halves; one of which was the narrative/tutorial portion; chapters 1 through 18, and 20, perhaps, though they might be able to be slimmed down a bit and some material moved to the second portion. The other half which is more of an "accessible reference" for advanced features; the material in chapter 19, but expanded a bit and with more discoverable per-topic chapters like the "Syntax and Semantics" section of the first book, plus the Nomicon material, and any of the topics which are missing.

Or, alternatively, just expanding on and integrating the "advanced X" material, Nomicon, and missing topics into the overall structure of the book.

Or another option would be to have the Book just be the Book focusing on the main narrative/tutorial introduction to the most common features, and have a Reference in two portions; one longer one which covers every major feature but in an accessible style with examples, followed by a more formal appendix covering each last little detail.

I guess ultimately what I'm saying (sorry for taking so long and so many diversions to say it, but as you point out, it is hard to get this right, and I've been thinking about what I'd be looking for as I write), is that there should be some place that has an "accessible reference" to all major features which is organized somewhat like the "syntax and semantics" section of the first edition book. The second edition book, chapters 1 through 18, is definitely a better organization as a book than the first edition, but that structure doesn't lend itself well to covering every feature, and as you point out, you wouldn't want it to.

But the Reference also isn't a friendly place to point people, both because of the "incomplete" warnings but also because it's written in a more formal style.

And the fragmentation into the Book, Nomicon, Rust by Example, stdlib docs, 2018 Edition Guide, Cookbook, Reference, Cargo Guide, Unstable Book, along with some of the reorgs along the way, can sometimes make it a bit hard to figure out the right place to look. I feel like there should be one document somewhere that has a reasonable accessible introduction, with examples, to every feature, in addition to the more formal and succinct Reference.

Maybe I should put my money where my mouth is and try to compile something like what I mean. It would help to have a little bit of buy in from docs team leadership, though, so that there would be a hope of it getting merged and maintained. Perhaps a docs RFC would be appropriate?

Just curious, why are those constraints there?