doc: fix where we forgot to target Windows users

[rakyll]

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.

• Go through all docs to evaluate if the docs are Windows friendly.
• Document instructions to set PATH a la what we have done for GOPATH, https://golang.org/wiki/SettingGOPATH. Refer to this doc where possible.
• Use https://golang.org/wiki/SettingGOPATH consistently everywhere.
• Produce a screencast similar to https://www.youtube.com/watch?v=XCsL89YtqCs for Windows users.

/cc @bradfitz @Cbro @rsc

[quentinmit]

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.

[rakyll]

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]

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]

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.

[quentinmit]

@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]

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

[techtonik]

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]

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]

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

[rsc]

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]

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

[as]

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]

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]

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

[gopherbot]

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

[disco0]

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]

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