Add more documentation links

[ckaran]

Summary

https://www.rust-lang.org/learn has some links to various documentation, but I think that there need to be significantly more. For example, the following is partial list that I'd like to see linked to:

• If you know where to look, you'll find each of these pages. But they aren't on the landing page, which is really weird.
  • https://doc.rust-lang.org/proc_macro/index.html
  • https://doc.rust-lang.org/core/index.html
  • https://doc.rust-lang.org/test/index.html - OK, it's experimental & nightly only, so I can see why this is hidden, but if it ever stabilizes then it should be on the landing page somewhere.
• https://rust-lang.github.io/api-guidelines/ - The API guidelines tell new crate authors how to write a good crate. Once I found it, its checklist became my go-to resource for gauging how well I've written my code.
• https://rust-unofficial.github.io/patterns/ - Necessary so that when someone says 'use the builder pattern' or 'use the newtype pattern', others can understand. Also helpful when you're learning what patterns are common in rust, and how to implement them so that when others read your code, they know what to expect.
• https://rust-lang-nursery.github.io/rust-cookbook/ - Quoting the book directly: "This cookbook is intended for new Rust programmers, so that they may quickly get an overview of the capabilities of the Rust crate ecosystem. It is also intended for experienced Rust programmers, who should find in the recipes an easy reminder of how to accomplish common tasks."

Motivation

Rust is powerful, but that power can only be accessed by new users by reading the documentation. Which they will not be able to do easily if it isn't exposed to them in a relatively flat space (like having it all on the landing page at https://www.rust-lang.org/learn). I actually didn't know about https://doc.rust-lang.org/proc_macro/index.html and https://doc.rust-lang.org/test/index.html until I started digging around in my own installed .rustup directory, and I've been using rust since about the 1.19 days; what's a brand new user going to do???

Drawbacks

If anything is experimental, then it shouldn't be exposed in the stable docs. There should be a link to the nightly docs from the landing page somewhere, along with a big, bold banner explaining what nightly really means (use at your own risk).

Rationale and alternatives

Putting all the links in a single well-organized landing page makes it really, really easy to find documentation, as well as to browse the documentation when you aren't really sure what you're looking for. Alternatively, we can rely on various search engines, but that means that the user needs guess what they're looking for, probably end up asking a bunch of questions on various forums, and then eventually find out that the docs are right there on the rust-lang.org, but hidden from the landing page! That is bad form, and makes rust look bad.

Not doing this just makes rust needlessly harder to use.

Maintenance

There shouldn't be much in the way of maintenance, just adding some links to the landing page that point to where the rustdoc generated documentation lives. For the manually generated documentation, it may require more work (docs team?).

Unresolved Questions

None that I can think of.

[Manishearth]

https://rust-unofficial.github.io/patterns/ - Necessary so that when someone says 'use the builder pattern' or 'use the newtype pattern', others can understand. Also helpful when you're learning what patterns are common in rust, and how to implement them so that when others read your code, they know what to expect.

Note: we don't typically link to external resources.

---

I don't think proc macro / core are that useful for people first learning Rust. The API Guidelines and cookbook might be, and it would be worth making a PR to see where they might fit. Can't guarantee on merging it, we also need to ensure they're reasonably maintained (they seem to have an ... okay maintenance story)

[ckaran]

Note: we don't typically link to external resources.

Merge it back into the official docs then?

I don't think proc macro / core are that useful for people first learning Rust.

I agree that they aren't perfect for learning, but when you go to https://doc.rust-lang.org or https://docs.rust-lang.org, they both redirect to https://www.rust-lang.org/learn, so in this case 'learn' == 'docs'.

In all honesty, I think it would be better to have separate 'docs' and 'learn' pages, which each pointing to the other. 'docs' could be a proper superset, with 'learn' being the subset (kind of like how a trait object only exposes a portion of the complete object; that might actually be a useful metaphor for future organization).

As for making a PR, I'm kind of swamped with work and promises on other projects, so I don't think I'll have time to do a PR (at least not anytime within the next few months). If you don't get to it before summer, and if I have time, I'll try to make a real PR.

[Manishearth]

Merge it back into the official docs then?

This requires the rust teams to commit to officially maintaining this, which is not something we do lightly.

I agree that they aren't perfect for learning, but when you go to https://doc.rust-lang.org or https://docs.rust-lang.org, they both redirect to https://www.rust-lang.org/learn, so in this case 'learn' == 'docs'.

That's fair. I still don't think they belong there, and i'm not sure if we should split them back for this reason because I don't think proc_macro and core should be prominent on doc.rust-lang.org either.

[ckaran]

This requires the rust teams to commit to officially maintaining this, which is not something we do lightly.

I completely understand this problem, but documentation is critical for adoption and expansion. Put another way, is it better to have a single, well-documented source of truth, or is it better to have a bunch of people on different forums making posts that are their best guesses as to what the truth really is? Or to have the only answer be a post on stackoverflow from 5 years ago?

One of rust's many strengths is high-quality documentation that is updated and maintained as rust evolves. I don't know if the builder pattern or the newtype pattern will change in the future, but if they do change then the official documentation should explain it all. For example, imagine that a new macro is adopted into a future version of the core library that makes generation of builders not only easy, but 100% official. The builder pattern documentation will be updated to reflect this new information, but the post from 5 years ago won't be. Or, if the builder pattern is officially deprecated, anyone that is maintaining a codebase is likely to want to know that ASAP, and to know what the new, official pattern to replace it is.

because I don't think proc_macro and core should be prominent on doc.rust-lang.org either.

I disagree with this. docs.rust-lang.org should be it's own page, and should be a well-organized reference library of rust. learn.rust-lang.org should be children's library, guiding programmers along paths toward rust literacy. The two sections complement each other, and both are needed.

[Manishearth]

One of rust's many strengths is high-quality documentation that is updated and maintained as rust evolves.

It's precisely this commitment and expectation that makes this hard to do.

We can't wave a wand and make this happen for new documentation. Currently our documentation team as a whole is defunct (some parts are active), and while there are plans to revive it, taking on new projects is not something that can be done near-term.

I disagree with this. docs.rust-lang.org should be it's own page, and should be a well-organized reference library of rust. learn.rust-lang.org should be children's library, guiding programmers along paths toward rust literacy. The two sections complement each other, and both are needed.

That's https://doc.rust-lang.org/stable/reference/ , which is linked to on learn (and links to proc macros, etc). Learn is not supposed to just be a "children's library", however I think proc_macro and core are specific enough that they don't need to be promoted there. There are many other things that I see at their level of specificity that would need to be promoted too.

[ckaran]

It's precisely this commitment and expectation that makes this hard to do.

I agree, and I acknowledge that this is a conundrum. But I personally think that this is necessary for rust's growth.

That's https://doc.rust-lang.org/stable/reference/ , which is linked to on learn (and links to proc macros, etc)...

To find the proc macro crate, I had to:

1. Go to the reference.
2. Skim the table of contents until I saw something that looked likely (section 3.2).
3. Read through that section and notice that there is a subsection labeled the proc_macro crate.
4. Click the link in there to get to the actual proc-macro crate.

I was able to do that relatively efficiently only because I've gone through the docs enough times that I had an idea of where to look. I don't even know where to look to find a link to the test crate (and I even changed the URL to use nightly, which is something a new user might not think of). And as for the rest of the links that I provided, I have no idea where I would find them. I suspect that now that I know they exist, I could whip up a shell script to see if there are any links to them in my .rustup directory, but for something like the test crate that will turn up a HUGE number of false positives.

In short, this isn't something that the reference solves. It's really intended for the language itself, and a few crates that are so tightly tied to the compiler that they are practically part of the language. docs.rust-lang.org would point to the reference, but there would be additional stuff in there over and above what the reference provides.

[Manishearth]

To find the proc macro crate, I had to:

I mean, it's on the sidebar of https://doc.rust-lang.org/stable/std/ as well. The reference is where the concept is explained in more depth, but if your complaint is "I can't find the crate" then uh, the crate is on the sidebar of the website where you find rust's library docs, where you'd expect it to be.

---

Totally happy to have links to the cookbook and api guidelines, I think proc_macro and test are niche enough that they really shouldn't exist on the main doc pages. And not because they're not beginner enough -- we link to the nomicon on /learn! -- but because finding those crate docs is not a typical task people visiting this page would have. They don't teach you how to write proc macros/tests, so most people will get there from their learning materials, but if someone is really just looking for library documentation, we have a website for library documentation (https://doc.rust-lang.org/stable/std/) and there's a link on the side.

[ckaran]

I mean, it's on the sidebar of https://doc.rust-lang.org/stable/std/ as well. The reference is where the concept is explained in more depth, but if your complaint is "I can't find the crate" then uh, the crate is on the sidebar of the website where you find rust's library docs, where you'd expect it to be.

Yes, you're right, but the issue then is that you need to know that you click on the button for the standard library, and then stuff that isn't a part of the standard library will become visible to you. That's not obvious.

For what it's worth, until you just pointed it out to me I didn't realize it was there. I'll admit, I'm good at missing the obvious, but even so that organization feels like going through a back door to get where you want rather than walking straight in through the front door.

Totally happy to have links to the cookbook and api guidelines,

Thank you! Should I make a PR for that, or would you be willing to add them in?

I think proc_macro and test are niche enough that they really shouldn't exist on the main doc pages.

Again, I disagree with you on this. https://docs.rust-lang.org should be as complete a reference as possible, but https://www.rust-lang.org/learn (or maybe create https://learn.rust-lang.org) should be organized as you suggest.

I know that creating a tree of pages feels like the right thing to do, but part of the issue is that sometimes you don't really know what you're looking for until you find it. Having a list of titles, organized by general sections but all on one page, means that you can scroll through until something looks likely, even when you don't know the right words to describe it.

[Manishearth]

Yes, you're right, but the issue then is that you need to know that you click on the button for the standard library, and then stuff that isn't a part of the standard library will become visible to you. That's not obvious.

I mean, that's kind of the problem with the word "standard library", they are a part of the "standard library", just not std, which are synonyms-but-not-quite.

But like: sure, they're not in std. Does that matter here? If someone is looking for them presumably they do not know that they're separate crates, and the first place they'd look is the standard library documentation.

If they do know that they're separate crates, docs.rs/proc_macro works fine.

It's not perfect, but I don't think they really need to be here.

Thank you! Should I make a PR for that, or would you be willing to add them in?

Go for it

Again, I disagree with you on this. https://docs.rust-lang.org should be as complete a reference as possible, but https://www.rust-lang.org/learn (or maybe create https://learn.rust-lang.org) should be organized as you suggest.

The reference exists to be "as complete a reference as possible". I'd be more amenable to this if you were requesting linking to a "proc macro guide", but it's just the crate. There's also the alloc crate, and more might be added in the future. I don't think it's a good idea to just link to a lot of crates. Like, my perspective here is that there are a lot of things that I consider to be at the same level as "finding the proc_macro crate", and it's just not a good idea, as policy, to include them ad hoc.

[ckaran]

OK, I'll work on a PR for that tomorrow. I'm going to be a first-time contributor, so I'd be grateful if you reviewed what I did extra-carefully, to make sure I don't make a mess of things.

[ckaran]

@Manishearth I'm sorry about taking so long, I got behind at my day job. I created #1446, would you mind taking a look at it?