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.

[jschulenklopper]

Not sure when it started to work, but go tool tour worked fine after retrieving the package (on my macOS machine). If the instructions for an offline tour would include that command, it could be good resolution for this ticket.

(I also mentioned this in the Golang Tour tracker, so if this repository isn't for the Tour at all, as mentioned ^, it could be closed here?)

[mandeepsingh-private]

"go tool tour" works on Mac.

[jschulenklopper]

"go tool tour" works on Mac.

Yes, that's what I said. Unfortunately, the instructions aren't updated yet.

[bradfitz]

"go tool tour" is dead as of Go 1.12. Maybe that should be in the release notes (@andybons, @dmitshur, @ianlancetaylor).

But the formatting at https://tour.golang.org/welcome/3 is a mess and doesn't seem to match https://github.com/golang/tour/blob/master/content/welcome.article#L80

Let's make this bug about fixing that.

[gopherbot]

Change https://golang.org/cl/158618 mentions this issue: doc: note go tool tour removal in 1.12 release notes

[ra1u]

At page https://tour.golang.org/welcome/3 it is specified that command

go get golang.org/x/tour
tour

is way to go. But looks like that first command has no effect,

It is also unclear what and where software is installed.

For example command

go get -v golang.org/x/tour

does not output anything on std-out, except it seems to return correct exit code. I cant find tour binary on my system

After some playing around with go help , my setup is now:

git clone https://github.com/golang/tour
cd tour
go build
./tour

And this seems to work for my particular debian system (your mileage may vary)

Extra:

I later found out that binary is located at $HOME/go/bin/tour, but i am not sure if package is installed from git or from go get.

[ALTree]

But the formatting at https://tour.golang.org/welcome/3 is a mess and doesn't seem to match > https://github.com/golang/tour/blob/master/content/welcome.article#L80

Let's make this bug about fixing that.

The formatting issue was fixed in 7de0bd1d74c6d868b2007ca43ea240671a6618f1, so we can close this.

I later found out that binary is located at $HOME/go/bin/tour, but i am not sure if package is installed from git or from go get.

It's from go get.

[dmitshur]

@ra1u Thank you for the helpful experience report.

I've factored out the issue of the welcome/3 slide missing instructions for how to install Go into #34585. I agree we should fix that.

[gopherbot]

Change https://golang.org/cl/197857 mentions this issue: content: make welcome/3 slide more beginner friendly