Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
rpjday opened this issue Apr 12, 2018 · 18 comments
Closed

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

rpjday opened this issue Apr 12, 2018 · 18 comments
Labels
Documentation FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@rpjday
Copy link

rpjday commented Apr 12, 2018

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
Copy link
Member

ALTree commented Apr 12, 2018

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.

@andybons andybons changed the title Instructions for running Go tour offline are deficient x/tour: instructions for running Go tour offline are deficient Apr 12, 2018
@gopherbot gopherbot added this to the Unreleased milestone Apr 12, 2018
@andybons andybons added NeedsFix The path to resolution is known, but the work has not been done. help wanted Documentation labels Apr 12, 2018
@agnivade
Copy link
Contributor

agnivade commented Apr 12, 2018

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
Copy link
Author

rpjday commented Apr 12, 2018

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
Copy link
Contributor

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
Copy link
Member

ALTree commented Apr 12, 2018

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

@ALTree ALTree added NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. and removed NeedsFix The path to resolution is known, but the work has not been done. help wanted labels Apr 12, 2018
@agnivade
Copy link
Contributor

ping @ianlancetaylor, @bradfitz for decision.

@bradfitz
Copy link
Contributor

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
Copy link

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?)

@jschulenklopper

This comment has been minimized.

@mandeepsingh-private
Copy link

"go tool tour" works on Mac.

@jschulenklopper
Copy link

"go tool tour" works on Mac.

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

@bradfitz
Copy link
Contributor

"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.

@bradfitz bradfitz changed the title x/tour: instructions for running Go tour offline are deficient x/tour: instructions for running Go tour offline are malformatted Jan 18, 2019
@bradfitz bradfitz added the NeedsFix The path to resolution is known, but the work has not been done. label Jan 18, 2019
@gopherbot gopherbot removed the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Jan 18, 2019
@gopherbot
Copy link

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

gopherbot pushed a commit that referenced this issue Jan 30, 2019
Note the removal of the go tool tour command in the Go 1.12 release
notes.

Updates #24819

Change-Id: I258ab9401ea2cc06a83328c67299376fcf23c980
Reviewed-on: https://go-review.googlesource.com/c/158618
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
nebulabox pushed a commit to nebulabox/go that referenced this issue Feb 18, 2019
Note the removal of the go tool tour command in the Go 1.12 release
notes.

Updates golang#24819

Change-Id: I258ab9401ea2cc06a83328c67299376fcf23c980
Reviewed-on: https://go-review.googlesource.com/c/158618
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
nebulabox pushed a commit to nebulabox/go that referenced this issue Feb 20, 2019
Note the removal of the go tool tour command in the Go 1.12 release
notes.

Updates golang#24819

Change-Id: I258ab9401ea2cc06a83328c67299376fcf23c980
Reviewed-on: https://go-review.googlesource.com/c/158618
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@ra1u
Copy link

ra1u commented Apr 29, 2019

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
Copy link
Member

ALTree commented Sep 27, 2019

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
Copy link
Contributor

@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
Copy link

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

gopherbot pushed a commit to golang/tour that referenced this issue Oct 1, 2019
Re-add the link to installing Go on the welcome/3 slide,
because it's a pre-requisite for being able to run go get.

This was included before, but got lost in a refactor after
the tour binary moved out of the Go distribution.

Additionally, make it more clear that installing the tour
locally is an optional step that only needs to be done if
one wishes to run the tour offline; it's not mandatory to
get through the tour. Running the tour online has a lower
overhead, and should help keep the tour accessible to more
people.

Fixes golang/go#34585
Updates golang/go#24819

Change-Id: If5f51e9e876722a86afca054bf78428f78bb3076
Reviewed-on: https://go-review.googlesource.com/c/tour/+/197857
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
@idopshik

This comment has been minimized.

@golang golang locked and limited conversation to collaborators Apr 27, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests