Some of the tutorial pages might be out-of-date

I am noticing that there (seems, I'm a newbie here, sorry) to be several errors in the tutorials. Also, I have questions about some of the text surrounding the examples.

What is the best way to communicate these issues back to the community so that those with expertise in the tutorials can address them? Creating a separate topic for each one might not be very efficient, although there could be good reasons for doing things that way, too. Again, I'm new here and just learning the ropes.

As you reply, please keep in mind that these are problems with the tutorials themselves, not the rust language, per se. The sorts of things that create stumblebums for us newbies. IOW, I am not reporting problems with rust, or difficulties understanding rust itself. (Rust is probably just fine!)

[EDIT: I wonder if there is a way for the tutorial system to automatically report errors in unmodified examples so that they can be given immediate attention before a new user encounters them (allowing, of course, for those examples that are supposed to fail forcing the learner to correct the code). Since rust generates an error if the code doesn't compile, this should be fairly straightforward, and could be performed each time there is an update to rust, I think.]

I believe you. But can you be explicit about which tutorials?

The official books/tutorials tend to have GitHub repos where you can report issues and whatnot. PRs are probably even better if well written. Even then, it's a volunteer community effort to maintain everything, so I can't say how fast things would move.[1]

This forum is a good place to ask.


  1. I have a backlog of Rust By Example suggestions to try to get applied, but actually doing so would take a lot of time... ↩︎

3 Likes

Once I figure out where to post them, sure, and I will. Where are the specific repos on github for the tutorials?

:slight_smile: Going in circles I think. Each tutorial may be in a different repo. So you have to first tell us which tutorials, then someone can tell you where the repo it.

1 Like

In mdBook books (which are used for a lot of the rust-lang documentation that isn't rustdoc), the top right corner has a GitHub logo

image

which links to the repository for that book.

5 Likes

That covers the tutorials linked to from the rust homepage:

Everything else on that page can be found by clicking the GitHub logo except for the rust and web assembly book for whatever reason, but that does have a link on the first page:

So... it looks to me that the repo for all tutorials appears to be the same one in the rust github. Thus, all issues and problems can be reported to the "issues" list for the tutorials repo; there is no need to identify individual repo for a particular tutorial then?

Are there still other tutorials that are not included in that long list of tutorials at https://github.com/rust-lang/rust-by-example/tree/master/src? To be clear, at this point, I am only referring to tutorials, not The Book or Rustlings.

Or am I still "going in circles?" Thank you for helping me to map out the process.

Then it sounds like the thing you are calling “all tutorials” or “the tutorials” is the thing whose title is “Rust by Example“. We didn’t know what you meant because Rust by Example is not particularly thought of as “the tutorials”.

You should report an issue to the Rust by Example repo if the text is on one of the pages of Rust by Example, and not if it isn't. Including the URL for the particular page you are discussing is always appropriate, and while you copy and paste the URL you can check if it starts with https://doc.rust-lang.org/rust-by-example/ like all the Rust by Example pages do. If it doesn't, then you must be looking at a document that is not part of Rust by Example.

In general for arbitrary documentation sites, it isn't always clear what the relationship is or even what the repository is, but once you have a guess, checking if the title of the document and the URL of the document match the name of the repository you're creating an issue in should help.

Further confirmation can be obtained by checking that the repository has a document which contains the text you want to file an issue about. For example, in https://doc.rust-lang.org/rust-by-example/scope/move.html I see the phrase “the previous owner can no longer be used”. If I go to https://github.com/rust-lang/rust-by-example and put that phrase in the GitHub search box, the only result is https://github.com/rust-lang/rust-by-example/blob/8f94061936e492159f4f6c09c0f917a7521893ff/src/scope/move.md?plain=1#L12. That tells me that if there was a problem with this text, it would be appropriate to report an issue to this repository, since the repository contains the text that I want to be changed. If I didn't find a match, I would look harder at what the repository does and doesn't contain.

Does that help clarify how to go about knowing where to report things?

3 Likes

Yes, and I doubt it could be clearer!

And I will use the term RBE from now on versus "tutorials." Thank you for correcting that.

1 Like

My RBE notes are here -- part Cliff's Notes, half Issue material. I haven't reviewed it since I wrote it so it's possible there's been some drift. Feel free to browse.[1]


  1. and anyone can feel free to turn the Issue material topics into PRs if they're still relevant, I just haven't had/put in the time to do so ↩︎

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.