cmd/go: workspace documentation is uninformative

[robpike]

The new workspace feature looks like a great thing, but the only helpful documentation is the design doc. The output from go help is barely rudimentary.

Look at where we start:

% go help work
Go workspace provides access to operations on workspaces.

Note that support for workspaces is built into many other commands,
not just 'go work'.

See 'go help modules' for information about Go's module system of
which workspaces are a part.

A workspace is specified by a go.work file that specifies a set of
module directories with the "use" directive. These modules are used
as root modules by the go command for builds and related operations.
A workspace that does not specify modules to be used cannot be used
to do builds from local modules.

To determine whether the go command is operating in workspace mode,
use the "go env GOWORK" command. This will specify the workspace
file being used.

Usage:

	go work <command> [arguments]

The commands are:

	edit        edit go.work from tools or scripts
	init        initialize workspace file
	sync        sync workspace build list to modules
	use         add modules to workspace file

Use "go help work <command>" for more information about a command.

It doesn't even say what a workspace is. It does kinda say how to make one, and hints at what it means, but it's just not good enough. The final sentence of the one substantive paragraph is unintelligible out of context.

What do they do? Why do I want one? Can I have more than one? What defines a workspace? etc. etc. The second sentence says they are so important they are implemented all over the place. What does that even mean and is it relevant?

The tip to go help modules is probably necessary but contains no direct information about workspaces and is itself a huge topic.

The individual commands add little:

% go help work use
usage: go work use [-r] [moddirs]

Use provides a command-line interface for adding directories,
optionally recursively, to a go.work file.

The -r flag searches recursively for modules in the argument directories.
% 

From the go help output alone I cannot understand this feature, what it is, what it solves, whether I should use it or not, and how to use it. Such an important new feature needs proper documentation support in the help system.

[ianlancetaylor]

CC @matloob @bcmills

[rsc]

@matloob is still working on workspace documentation

[bcmills]

@matloob is still working on workspace documentation

That's on me at the moment, I think‌ — I still owe him a review on CL 383854.

[matloob]

Hi, we now have a tutorial at https://go.dev/doc/tutorial/workspaces in addition to the reference documentation in https://go.dev/ref/mod#workspaces. I've submitted a CL (that will be cherry picked onto 1.18 and provides links to both of those docs from go help work.

[dmitshur]

The aforementioned CL has now been cherry-picked to release-branch.go1.18 via CL 389914 (commit 0b38b02).

[matloob]

I'm hoping that the workspace documentation improvements we've made address the sense that the documentation is uninformative.

Our plan with go command documentation is to have the website be the primary source of documentation rather than the command. So it's intentional that most of the documentation is on the website, and the go command documentation focuses only on the individual commands rather than workspaces as a whole.

If the documentation on the website is confusing or incomplete, we would definitely want to improve it.