gopls/doc: move contents of golang/go#36899 to documentation

This change adds a file that explains the different ways
of configuring your workspace with gopls. Ultimately, I think we should
move this to the documentation, but I didn't want to deal with
merge conflicts from my other CL, so moving it here to start.

Fixes golang/go#36899

Change-Id: I9217dc85a10cc6d0cbb4471509a186405d2e2088
Trust: Rebecca Stambler <>
Run-TryBot: Rebecca Stambler <>
gopls-CI: kokoro <>
TryBot-Result: Go Bot <>
Reviewed-by: Robert Findley <>
diff --git a/gopls/doc/ b/gopls/doc/
new file mode 100644
index 0000000..6f56bf5
--- /dev/null
+++ b/gopls/doc/
@@ -0,0 +1,75 @@
+# Setting up your workspace
+`gopls` supports both Go module and GOPATH modes. However, it needs a defined
+scope in which language features like references, rename, and implementation
+should operate.
+The following options are available for configuring this scope:
+## Module mode
+### One module
+If you are working with a single module, you can open the module root (the
+directory containing the `go.mod` file), a subdirectory within the module,
+or a parent directory containing the module.
+**Note**: If you open a parent directory containing a module, it must **only**
+contain that single module. Otherwise, you are working with multiple modules.
+### Multiple modules
+As of Jan 2020, if you are working with multiple modules, you will need to
+create a "workspace folder" for each module. This means that each module has
+its own scope, and features will not work across modules. We are currently
+working on addressing this limitation--see details about
+[experimental workspace module mode](#experimental-workspace-module-mode)
+In VS Code, you can create a workspace folder by setting up a
+[multi-root workspace](
+View the [documentation for your editor plugin]( to learn how to
+configure a workspace folder in your editor.
+#### Workspace module (experimental)
+Many `gopls` users would like to work with multiple modules at the same time
+([golang/go#32394](, and
+specifically, have features that work across modules. We plan to add support
+for this via a concept called the "workspace module", which is described in
+[this design document](
+This feature works by creating a temporary module that requires all of your
+workspace modules, meaning all of their dependencies must be compatible.
+The workspace module feature is currently available as an opt-in experiment,
+and it will allow you to work with multiple modules without creating workspace
+folders for each module. You can try it out by configuring the
+setting. If you try it and encounter issues, please
+[report them]( so we can address them
+before the feature is enabled by default.
+You can follow our progress on the workspace module work by looking at the
+open issues in the
+[gopls/workspace-module milestone](
+### GOPATH mode
+When opening a directory within your GOPATH, the workspace scope will be just
+that directory.
+### At your own risk
+Some users or companies may have projects that encompass one `$GOPATH`. If you
+open your entire `$GOPATH` or `$GOPATH/src` folder, the workspace scope will be
+your entire `GOPATH`. If your GOPATH is large, `gopls` to be very slow to start
+because it will try to find all of the Go files in the directory you have
+opened. It will then load all of the files it has found.
+To work around this case, you can create a new `$GOPATH` that contains only the
+packages you want to work on.
+If you have additional use cases that are not mentioned above, please
+[file a new issue](