Enhance the Visual Studio installation documentation

[ChrisDenton]

Problem you are trying to solve

While rustup will now offer to automatically install Visual Studio, this is not the right option for all users (for licensing or other reasons). And the manual Visual Studio install continues to be a pain point for new users. Between the console install instructions and the rustup book, there is still a failure to properly communicate the requirements. Making this effort harder is that the precise steps needed can change over time as new versions of Visual Studio are released.

There are also currently multiple places where people may go looking for install instructions. These might include:

• rustup-init.exe console instructions
• https://rustup.sh
• the rustup book
• the Rust Book (either online or in print)
• https://rust-lang.org
• chat, forums, etc

It would be good if these could all link to one central page that can be updated. See also rust-lang/book#3303.

Solution you'd like

Enhance the online docs to provide improved guidance to new users who are struggling to figure out the requirements. This would include having a walkthrough with screenshots and being clear about which Visual Studio version it applies to. The console instructions could be made more succinct (instead of "a wall of text") and link to the docs for people who need further guidance.

I would also suggest that such a walkthrough could either live at https://rustup.sh/msvc.html or redirect from there. This would allow for a shorter url which would be more convenient for consoles and printed books. Alternatively I could perhaps talk with the rust-lang.org team about setting up a redirect from that website.

Tasks

Preview Give feedback

1. [Windows] rustup-init.exe's on-screen instructions could be better #1363
   +0
2. Docs for Windows/MSVC toolchain: which workloads/components to install? #2809
   O-windows enhancement +2
3. rustup should suggest Windows 11 SDK while installing on Windows 11 #2912
   E-mentor O-windows enhancement help wanted +4

[ehuss]

I think it would be great to have clearer information. I think that one of the installation pages had screenshots at one point, but I don't remember where that was.

A while back I started work on an "Installation Guide". I have encountered users having difficulty getting started on all sorts of platforms (not just MSVC), not to mention cross-compilation problems. There's no less than 6 sites in the rust-lang org for how to install Rust, all of which are incomplete. I wonder if people would have interest in a broader guide for how to get started for all platforms? Ideally it wouldn't be necessary for the majority of users, but could be helpful for people with more unusual or advanced requirements or just wants more help.

I was also thinking it would be more independent from the rustup book, since it may be possible that a user isn't using rustup, but they still need to use MSVC.

Regardless, would it be sufficient in the short term to just update https://rust-lang.github.io/rustup/installation/windows.html (or add a sub-page) that includes step-by-step instructions?

[ChrisDenton]

My focus is very much MSVC because that's the target I'm most familiar with and where I regularly field support questions or see people struggling in chat. I hope anything that's done to help with msvc will also provide inspiration for helping with other platforms. However, I do think it's slightly different as installing the prerequisites is slightly more involved than for other tier 1 hosts. Or at least I don't see so many people struggling with other platforms.

Which is to say, I love the idea of a broader guide but I really would strongly prefer not to gate this on that. The new user experience is super important to me and, as I said, people do have issues with the vs prerequisites a lot.

And I do agree we need a single, canonical, place for install instructions to live. Having six(?!) places is not great maintenance wise, or just in general. Maybe rustup isn't the best place for it so if there's somewhere better could you point me to where and who to discuss this with? I'd like to get the ball rolling as early as possible.

Regardless, would it be sufficient in the short term to just update https://rust-lang.github.io/rustup/installation/windows.html (or add a sub-page) that includes step-by-step instructions?

This would indeed be a good first step. My idea would be to have a separate subpage specifically for msvc so that the main page can provide a brief summary and the msvc page won't feel the need to keep reminding people that gnu exists.

However, I don't want to end up adding yet more duplication of effort so if we can figure out a single location for installing prerequisites then I'd love to just do that in the first place.

[ChrisDenton]

Also, I'd reiterate the point about wanting a stable url that can be printed in a book without going stale. I'd also like for it to be short so it can be typed more easily. If it's still uncertain where such documentation should ultimately live then I would love to have some kind of redirection setup, maybe using a rust-lang.org url if not rustup.rs.

[ehuss]

I don't think there is any momentum to have a centralized set of installation directions, so I wouldn't wait on that. I can also feel my own distaste for such a thing, as that makes it seem that installing Rust is a really complex operation, and scare people away. I don't know of any other projects that have much more than a single page of installation instructions. If a user needs a manual just to install things, I feel like we've failed in some way.

The books have built-in redirect capabilities, so I wouldn't worry too much about links going stale.

I imagine it shouldn't be too hard to make a short-url somewhere that redirects. I personally don't have any opinion about rust-lang.org vs rustup.rs.

[ChrisDenton]

The books have built-in redirect capabilities, so I wouldn't worry too much about links going stale.

A printed book does not.

[ehuss]

I was meaning that if a printed book points to a URL like https://rust-lang.github.io/rustup/installation/windows.html, and then in some point in the future that changes, mdbook can redirect that to the correct location.

[ChrisDenton]

Ah I see. I didn't know mdbook could do redirects like that.

[garretwilson]

It's a bit ironic that this issue is plodding on for over a year, when the issue itself hasn't laid out what the requirements are. (See e.g. #2912).

Suggestion: if someone could at least summarize the true, up-to-date installation requirements here on this ticket, then whether you update the other documentation, consolidate the other documentation, or whatever would be less important. At least those searching the web could find this ticket and get a definitive answer.

[garretwilson]

Ah, after more searching, The rustup book has a section discussing selecting individual components. Maybe that will answer my questions.

[ChrisDenton]

There are now docs with a walkthrough: https://rust-lang.github.io/rustup/installation/windows-msvc.html

If you have any ideas for improving them then that would be great.

Edit: I typed this before I saw your last comment, sorry!

[garretwilson]

There are now docs with a walkthrough: https://rust-lang.github.io/rustup/installation/windows-msvc.html

I just now found those, thanks. So far they look pretty good! 👍 I'll try out the steps later today.