installation instructions are too daunting

[alexeagle]

discussed with @laszlocsomor

There are several problems with the first-time user experience. I estimate that many frontend developers haven't or won't try Bazel because of things like a Java dependency. Ideally we could measure install abandon rate, but let's try to improve it without metrics:

1. https://github.com/bazelbuild/bazel/blob/master/site/docs/install.md includes platform-specific stuff like bash/zsh, and mentions Java which should not be on the recommended installation path (nb. Frontend developers have a strong distaste for installing Java)

recommendation: install.md should only direct you to the installation instructions for your platform, and how to compile from source

2. Windows documentation is split into "using" and "installing"
   using: https://github.com/bazelbuild/bazel/blob/master/site/docs/windows.md
   installing: https://github.com/bazelbuild/bazel/blob/master/site/docs/install-windows.md
   but the distinction is broken: there are pre-requisites and again mentions of Java on the "using" page

recommendation: "installing" should have everything the user looks at when using Bazel for the first time (on a new machine), "using" should only have documentation I refer to periodically while developing

3. Java is mentioned in the installation instructions

We should only mention Java if the user is developing Java (java_library et al) or if they are following non-recommended installation instructions (aka broken installation).

For each platform, the installation page should recommend whichever method is simply "run this command" or "double-click here". Any other methods should be below the fold as alternatives.
For Brew, this means we should recommend the binary installer, not homebrew. (Note, we have an email discussion about how homebrew is currently broken and requires the user install Java themselves)

4. User is prompted to install prerequisites they may not need

This is partly because windows prereqs are mixed with the "usage" page - but in general, "optional dependencies" (those which are only needed with certain rules or use cases) should only be listed along with that feature, not in the path of every user doing their first install.

/cc @hansl

[dslomov]

@laszlocsomor for Windows updates

@philwo, @dslomov - let's decide whether the story on Mac should be brew cask or just plain installer.

@spomorski for documentation update.

[laszlocsomor]

Thanks Alex, I really like these suggestions. I'll rework the Windows page.

[davido]

You cannot drop Java dependency to use Bazel. You can hide Bazel dependency on Java, but I fail to see how this would help anyone.

So the right question to ask is not "How/where to hide the Bazel dependency on Java." but rather: "Why must Bazel depend on MSVC on Windows"?

This is not related to the documentation issues for frontend (JavaScript) projects, but rather to all backend projects as well, that do not depend on native code, and thus don't need C++ tool chain and trying to use Bazel on Windows.

On Linux I don't care, if it requires gcc, because it's already there. But after setting up all Windows VM mess, installing Java, MSYS and Python and trying to use Bazel, it's telling me that MSVC is required, even though, my frontend and backend projects don't have any cc_library rules and friends.

[laszlocsomor]

it's telling me that MSVC is required,

Actually it shouldn't be, since version 0.8.0 (see 1f61472). We accidentally omitted this from the release notes (I have proof that this was an honest mistake) and we forgot to update the documentation.

Do you see Bazel complaining about the missing compiler?

[davido]

Actually it shouldn't be, since version 0.8.0 (see 1f61472).

Thanks, for the pointer, I missed that (and it was long overdue). In fact, I stopped all activities related to Bazel on Windows after spending days in investigating inaccurate build outcomes on Windows in context of #4108. It turned out, that the most critical Bazel integration tests, like compiler integration e.g.: #4165 are inherently broken or not activated on that platform.

[dslomov]

@davido, I think your comments on this bug (and on some others as well) cross the boundary of constructive criticism into the realm of ranting and derailing.