x/tour: instructions for running Go tour offline are malformatted

[rpjday]

There seem to be two issues with the instructions for how to run the Go tour offline here.

First, on my Fedora system, even though I have installed Go 1.10.1 from binary rpms, running go tool tour doesn't work (perhaps this requires installing a distinct Fedora package that is not mentioned):

$ go tool tour
go tool: no such tool "tour"
$

The second issue is that, before trying to run these commands:

$ go get golang.org/x/tour/gotour
$ gotour

the reader should be reminded to add ${GOPATH}/bin to their search path.

[ALTree]

Thanks for the report. I have a comment about your first point.

First, on my Fedora system, even though I have installed Go 1.10.1 from binary rpms, running go tool tour doesn't work

The full paragraph says:

To run the tour locally first download and install Go then start the tour from the command line:
go tool tour

The two things go together: it's one sentence. The hyperlink at the "download and install Go" text points to golang.org/dl, which instructs the reader to install go from the pre-compiled binaries. It is implied that you can expect the command to work out-of-the-box only if you followed the instructions immediately above and installed go from the website.

While we could fill the docs with notes and warnings about possible different ways to do things (like installing from OS packages), I think this would make the documentation very unpleasant to read. In general, it's clearer to document a simple, happy path (especially in tutorials like the Go Tour, where it's generally a bad idea to hit the reader with too much -possibly useless- text). Users are expected to follow that path, or be ready to troubleshot their problems if they decide to deviate.

[agnivade]

the reader should be reminded to add ${GOPATH}/bin to their search path.

I think that is unnecessary. Next up, people will start asking for this reminder to be added under all x/tools/ subrepos as well. And following that logic, maybe all Go repos on github as well.

We should just need one page to clearly document the installation steps. And that is very well documented at https://golang.org/doc/install.

[rpjday]

I'm not suggesting that that advice be added everywhere, but given that it's on page three of the entire tour, I don't think it's out of place to make sure readers know how to set up properly. And the page you're referring to is not part of the tour. Why so much resistance to adding a single line to make sure readers don't run into a problem?

[agnivade]

Not at all. My only concern was that information might get duplicated into multiple places. Otherwise I have no strong opinions on this. If it helps newcomers, I am all for it. 👍

Sorry if I was misunderstood.

[ALTree]

I don't understand why this has been labelled as NeedsFix. Tracker guidelines says:

The path to resolution is known

That's not the case. It's not clear what exactly should be done here. This is a needsDecision, if anything. And anyway we don't really track tour improvemen suggestions here. The tour tracker is at https://github.com/golang/tour

[agnivade]

ping @ianlancetaylor, @bradfitz for decision.

[bradfitz]

For completeness, since I didn't see it mentioned above: even if the user is confused by both offline install options, there's always a third option: using the web-based tour that the user's already found if they're reading that page.

I don't really want to mention $GOPATH because $GOPATH might be implicit, and it might be spelled %GOPATH% on Windows, if it's set at all. Likewise, I don't want to assume bash and recommend running $(go list -f {{.Target}} golang.org/x/tour/gotour) or something gross.

If anything, we could modify the cmd/go tool to know what "tour" means on the case where the binary isn't found in the tool dir, and then it can spit out detailed, OS-specific install instructions on failure.

Then we could even remove some of the text on the tour page and only mention go tool tour.