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

doc: fix where we forgot to target Windows users #18581

Open
rakyll opened this issue Jan 9, 2017 · 17 comments

Comments

@rakyll
Copy link
Member

commented Jan 9, 2017

A significant amount of Go users are Windows users even though the official Go documentation is lacking references targeting the Windows users. This is frustrating the Windows and end up them relying on third party sources which are often not up to date or not documenting the best practices.

This is a tracking issue to improve Windows-specific instructions in docs.

/cc @bradfitz @Cbro @rsc

@rakyll rakyll added the Proposal label Jan 9, 2017

@quentinmit

This comment has been minimized.

Copy link
Contributor

commented Jan 9, 2017

This seems too abstract to me. What does "first class" and "parity" mean here? As a hypothetical new Go users on Windows, I would go to golang.org, click "Download Go", click "installation instructions", and then I get a page that seems to explicitly cover Windows.

No disagreement that all the docs could be improved, but I don't see anything that's doesn't look like parity to me.

@quentinmit quentinmit added this to the Proposal milestone Jan 9, 2017

@rakyll

This comment has been minimized.

Copy link
Member Author

commented Jan 9, 2017

I would go to golang.org, click "Download Go", click "installation instructions", and then I get a page that seems to explicitly cover Windows.

The very example you give is not covering Windows for "test your installation" section, see https://golang.org/doc/install#testing. The very essential doc to write your first program doesn't care about Windows users either, see https://golang.org/doc/code.html.

We are OK with the quality of our docs because we are already a Unix users, know how to fill the gaps and have a good understanding what to do on Windows when we see a $ export GOPATH=$HOME/work.

The definition of "first class" is "If there is a Unix-specific instruction, there should be a Windows-specific instruction".

I am going to extend the proposal to clarify.

@as

This comment has been minimized.

Copy link
Contributor

commented Jan 10, 2017

As a user of Go on most currently-supported operating systems, I offer my personal experience in the Windows production environment:

Most of the Windows developers i've encountered are as equally confused by set GOPATH=C:\%userprofile%\work as they are by export GOPATH=$HOME/work

A majority of these users will expect out-of-the-box integration with an IDE such as Visual Studio. Given time, It would not surprise me if the Windows-documentation degenerated to Press the start menu, open the run bar, type cmd.exe, and press Enter...

While these are helpful instructions for a beginner, I recommend defining a minimum entry criteria (of what the 'gaps' in 'filling the gaps' are) if the documentation is to target Windows users, or more-specifically, Windows developers.

I agree that the Windows platform could have more docs, but I caution against attempting to make Windows the target platform for Go for this reason.

@rakyll

This comment has been minimized.

Copy link
Member Author

commented Jan 10, 2017

It would not surprise me if the Windows-documentation degenerated to Press the start menu, open the run bar, type cmd.exe, and press Enter...

I don't think we need to add any noise to the existing docs to make it Windows friendly. We can just give a link to a wiki page that explains how to set an env variable on Windows. We already created an all inclusive guide for GOPATH at https://golang.org/wiki/SettingGOPATH. For example, we consistently need to refer to that doc all around.

@rakyll rakyll changed the title proposal: docs should target Windows users proposal: docs should also target Windows users Jan 10, 2017

@quentinmit

This comment has been minimized.

Copy link
Contributor

commented Jan 10, 2017

@rakyll The "test your installation" section you cite does contain Windows-specific instructions:

On Windows, follow the instructions above to set the GOPATH environment variable on your system.

@rakyll

This comment has been minimized.

Copy link
Member Author

commented Jan 10, 2017

@quentinmit Today I realized that there is actually a full Windows-specific guide if you download the MSI installer. See https://tip.golang.org/doc/install?download=go1.7.4.windows-amd64.msi (downloads the installer upon load).

FWIW, I am converting this proposal into a tracking issue. There are a bunch of things to be improved here and there. I don't think we need to discuss them all on this proposal but evaluate case by case on CL review.

@rakyll rakyll changed the title proposal: docs should also target Windows users doc: fix where we forgot to target Windows users Jan 10, 2017

@rakyll rakyll modified the milestones: Go1.9, Proposal Jan 10, 2017

@rakyll rakyll removed the Proposal label Jan 10, 2017

@techtonik

This comment has been minimized.

Copy link

commented Apr 17, 2017

I just run into the issue that I need to use https://golang.org/pkg/path/filepath/#Base instead of https://golang.org/pkg/path/#Base on Windows.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Apr 17, 2017

You should use filepath for file paths on all systems, not just Windows. I'm not sure what that has to do with this issue, though.

@techtonik

This comment has been minimized.

Copy link

commented Apr 18, 2017

@rsc just link path.Base to path/filepath.Base description if that's possible.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Apr 20, 2017

https://golang.org/pkg/path/ says:

Package path implements utility routines for manipulating slash-separated paths.

To manipulate operating system paths, use the path/filepath package.

We're not going to put that text in the docs for every function in the package.

@techtonik

This comment has been minimized.

Copy link

commented Apr 21, 2017

That text is too long. "See also path/filepath." is still a worthy addition.

@as

This comment has been minimized.

Copy link
Contributor

commented Apr 21, 2017

Cluttering godoc with catchphrases referencing other packages is pedantic. After the doc is read once, and the primary information internalized, these worthy additions become chaff covering the grains of importance.

@techtonik

This comment has been minimized.

Copy link

commented Apr 25, 2017

If I use Go daily then of course, reminder to use path/filepath instead of path will be a nuisance. But for newcomers and whose who use Go infrequently, this layer of information may occasionally be handy. Perhaps there will be a mechanism to make it a layer.

@rakyll

This comment has been minimized.

Copy link
Member Author

commented Apr 25, 2017

Let's please move the discussion to its own issue #20117, this tracking bug is really irrelevant to the specific problem reported here.

@gopherbot

This comment has been minimized.

Copy link

commented Jun 29, 2017

CL https://golang.org/cl/47254 mentions this issue.

gopherbot pushed a commit that referenced this issue Jun 30, 2017
os: add documentation for Windows users
Updates #18581
Updates #20858

Change-Id: I6b5ce0e255a42c028d46815fff5a5aca68690fd9
Reviewed-on: https://go-review.googlesource.com/47254
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
@disco0

This comment has been minimized.

Copy link

commented Nov 14, 2017

We already created an all inclusive guide for GOPATH at https://golang.org/wiki/SettingGOPATH. For example, we consistently need to refer to that doc all around.

I saw this url while using the help command, just a heads up that isn't a valid wiki page atm—its been renamed a few times in the last couple months, and its currently located at wiki/Setting-GOPATH. Is there a good reason for the space/dash, or should it just get switched back and skip changing the help docs?

@ianlancetaylor

This comment has been minimized.

Copy link
Contributor

commented Nov 14, 2017

@disco0 I don't know what happened to that wiki page, but it's back at SettingGOPATH now.

@rsc rsc modified the milestones: Go1.10, Unplanned Dec 1, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
9 participants
You can’t perform that action at this time.