-
Notifications
You must be signed in to change notification settings - Fork 289
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add more documentation links #1433
Comments
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) |
Merge it back into the official docs then?
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. |
This requires the rust teams to commit to officially maintaining this, which is not something we do lightly.
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. |
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.
I disagree with this. |
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.
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. |
I agree, and I acknowledge that this is a conundrum. But I personally think that this is necessary for rust's growth.
To find the proc macro crate, I had to:
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 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. |
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 |
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.
Thank you! Should I make a PR for that, or would you be willing to add them in?
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. |
I mean, that's kind of the problem with the word "standard library", they are a part of the "standard library", just not But like: sure, they're not in 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.
Go for it
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 |
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. |
@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? |
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:
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.
The text was updated successfully, but these errors were encountered: