feat: Added additional resources to learn.rust-lang.org. #1446
Conversation
Added 3 additional resources to learn.rust-lang.org in their own section: - https://rust-lang.github.io/api-guidelines - https://rust-unofficial.github.io/patterns - https://rust-lang-nursery.github.io/rust-cookbook **NOTE!** This commit requires additional work; I am not fluent in any language other than US English, and so haven't attempted to add translations. native speakers that are able to make the necessary changes are required here.
|
So I don't think this should be a separate section, we should just add more buttons to the existing long list. And as I mentioned before, we do not link to unofficial resources on this website. |
Which one?
OK, I misunderstood what you meant then. Do you mean that you want me to copy the external documentation to some internal location? Or should the links be placed somewhere different? |
No, I'm saying that the rust-unofficial.github.io content cannot be linked here. The other two are fine, rust-lang and rust-lang-nursery are official sources.
I was going to suggest the "read the core documentation" section but that's not quite right. A new "additional resources" section may make more sense. cc @skade who might have ideas on how best to surface this |
|
Phew, I guess this merits a new section. There's also upcoming things like the async book and such that might not fit the current. |
|
After some discussion it does seem like cookbook is not being maintained as much, and I'm unsure about api-guidelines. @KodrAus @rust-lang/libs can y'all:
(In general we ought to defer to the teams on site content, sorry for the misleading signals, @ckaran ) |
Makes complete sense to me! I'm just trying to be helpful, especially as rust can have a steep learning curve. I just thought of another good resource that, while not official, is run by someone well-known within the community: @dtolnay's proc-macro-workshop. The issue is that it is yet another resource that is not official. Maybe what is needed is a whole new section: 'Additional UNOFFICIAL Resources', with a big warning that those resources aren't maintained by the rust team, and as such may go away or be unhelpful in some way. Getting back to this PR in particular, I'm going to hold off on making any more changes until some of the other questions are resolved. I don't like churn in documentation, it wrecks my muscle memory when I'm looking for something, and I suspect others are the same. Once the questions are resolved, I can modify this PR. |
There's a strict policy to not link to unofficial resources on the website. They still need vetting and tracking and it's impossible to untangle yourself from the endorsement. |
What about asking the authors if they would donate the material to the internal repository? At that point, the rust team would have complete control over the material and could vet it. The original authors would need to issue PRs to make updates to the material, but that shouldn't be too big a hurdle. It might even help bootstrap getting the documentation team restarted by simply asking if really good authors would be a part of it... |
|
You misunderstand; this is not a matter of control, this is a matter of quality. For a resource to be official it needs to be maintained, and maintained by us, by a functional team with goals. The "by us" part is not the hard part here, it's necessary but far from sufficient. We do not currently have the bandwidth to vet and maintain these projects. We're working on growing it, but it's more of an organizational problem than simply a lack of documentation-minded people. Documentation is a cross-cutting concern and is as such tricky to make work in an open source organization. This is a symptom of a bigger problem, and will not be solved by pulling in more resources to maintain. |
|
I see. In that case, there is very little that can be done currently. The API guidelines should probably go in, but if the cookbook isn't as well maintained as the other parts, then it should stay out. The rest can't go in at all. Where should the API guidelines go? In their own section? |
|
Whether they should go in, and where they should go, is up to the libs team, since it's really not clear if the API guidelines are strongly maintained. |
|
@Manishearth OK, so should I close out this PR entirely, and log an issue with one of the teams? If so, which team? |
|
Doesn't matter if the PR is closed, I have already tagged the libs team here with my questions |
|
Rust team, the libs team has not responded. I can't say about api-guidelines but the cookbook is definitely outdated. I suggest we close this out and maybe create a new issue to track adding additional official resources. |
Relates to issue #1433.
Added 3 additional resources to learn.rust-lang.org in their own section:
NOTE! This commit requires additional work; I am not fluent in any
language other than US English, and so haven't attempted to add translations.
native speakers that are able to make the necessary changes are required
here.