-
Notifications
You must be signed in to change notification settings - Fork 18k
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
cmd/go: workspace documentation is uninformative #51301
Comments
@matloob is still working on workspace documentation |
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 |
I'm hoping that the workspace documentation improvements we've made address the sense that the documentation is uninformative. Our plan with If the documentation on the website is confusing or incomplete, we would definitely want to improve it. |
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:
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:
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.The text was updated successfully, but these errors were encountered: