README: add troubleshooting section, some cleanup

Change-Id: I92cd750dcfb393bf7cd33257f02d8d57c369f534
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/286472
Trust: Rebecca Stambler <[email protected]>
Run-TryBot: Rebecca Stambler <[email protected]>
Reviewed-by: Hyang-Ah Hana Kim <[email protected]>

Author: stamblerre

README.md

@@ -8,12 +8,6 @@
 provides rich language support for the
 [Go programming language](https://golang.org/).
 
-> 📣 We will enable the language server ([`gopls`]) by default in the end of Jan
-> 2021. We recommend switching to the language server now
-> (`"go.useLanguageServer": true`) to confirm it works well for you. Please
-> [file a new issue](https://github.com/golang/vscode-go/issues/new/choose) if
-> you notice bugs or missing features.
-
 ## Quick Start
 
 Welcome! 👋🏻<br/>
@@ -23,7 +17,7 @@ extension fits your needs and enhances your development experience.
 * **Step 1.** If you haven't done so already, install [Go](https://golang.org)
   and the [VS Code Go extension].
   * [Go installation guide]. This extension works best with Go 1.14+.
-  * [Manage extensions in VS Code].
+  * [Managing extensions in VS Code].
 * **Step 2.** To activate the extension, open any directory or workspace
   containing Go code. Once activated, the [Go status bar](docs/ui.md) will
   appear in the bottom left corner of the window and show the recognized Go
@@ -40,23 +34,23 @@ extension fits your needs and enhances your development experience.
 
 You are ready to Go :-) &nbsp;&nbsp; 🎉🎉🎉
 
-Please be sure to learn more about many [features](#features) of this extension
-as well as how to [customize](#customization) them. Take a look at
+Please be sure to learn more about the many [features](#features) of this
+extension, as well as how to [customize](#customization) them. Take a look at
 [Troubleshooting](docs/troubleshooting.md) and [Help](#ask-for-help) for further
 guidance.
 
 If you are new to Go, [this article](https://golang.org/doc/code.html) provides
-the overview on go code organization and basic `go` commands. The recent
-[Go open source live video] featured VS Code Go and demonstrated how other
-Gophers use the features to enhance their Go development workflow.
+the overview on Go code organization and basic `go` commands. Watch [this video
+from the Go Open Source Live conference] for an explanation of how to build
+your first Go application using VS Code Go.
 
 ## Features
 
 This extension provides many features, including [IntelliSense],
-[code navigation], [code editing] support. It also shows [diagnostics] as you
-work and provides enhanced support for [testing] and [debugging] your programs.
-See the [full feature breakdown] for more details and to learn how to tune the
-behavior.
+[code navigation], and [code editing] support. It also shows [diagnostics] as
+you work and provides enhanced support for [testing] and [debugging] your
+programs. See the [full feature breakdown] for more details and to learn how to
+tune its behavior.
 
 <p align=center>
 <img src="docs/images/completion-signature-help.gif" width=75%>
@@ -68,68 +62,75 @@ In addition to integrated editing features, the extension provides several
 commands for working with Go files. You can access any of these by opening the
 Command Palette (`Ctrl+Shift+P` on Linux/Windows and `Cmd+Shift+P` on Mac), and
 then typing in the command name. See the
-[full list of commands](docs/commands.md#detailed-list) provided by the
+[full list of commands](docs/commands.md#detailed-list) provided by this
 extension.
 
 <p align=center>
 <img src="docs/images/toggletestfile.gif" width=75%>
 <br/><em>(Toggle Test File)</em></p>
 
-**⚠️ Note**: the default syntax highlighting for Go files is provided by the
+**⚠️ Note**: the default syntax highlighting for Go files is provided by a
 [TextMate rule](https://github.com/jeff-hykin/better-go-syntax) embedded in VS
 Code, not by this extension.
 
 ## Tools
 
 The extension uses a few command-line tools developed by the Go community. In
-particular, `go`, `gopls`, and `dlv` are used to implement build/test, language
-features, and debugging functionalities of this extension. See the
-[tools documentation](docs/tools.md) for a complete list of tools the extension
-depends on.
-
-In order to locate the command-line tools, the extension searches `$GOPATH/bin`
-and directories specified in the `PATH` environment variable (or `Path` in
-Windows) with which the VS Code process has started. If the tools are not found,
-the extension will prompt you to install the missing tools and show the "⚠️
-Analysis Tools Missing" warning in the bottom right corner. Please install them
-by responding to the warning notification, or by manually running the `Go:
-Install/Update Go Tools` command. The extension will run the
-[`go get`](https://golang.org/cmd/go) command to install them.
+particular, `go`, `gopls`, and `dlv` **must** be installed for this extension
+to work correctly. See the [tools documentation](docs/tools.md) for a complete
+list of tools the extension depends on.
+
+In order to locate these command-line tools, the extension searches
+`GOPATH/bin` and directories specified in the `PATH` environment variable (or
+`Path` on Windows) with which the VS Code process has started. If the tools are
+not found, the extension will prompt you to install the missing tools and show
+the "⚠️ Analysis Tools Missing" warning in the bottom right corner. Please
+install them by responding to the warning notification, or by manually running
+the [`Go: Install/Update Go Tools` command].
 
 ## Setting up your workspace
 
 [Go modules](https://golang.org/ref/mod) are how Go manages dependencies in
 recent versions of Go. Modules replace the `GOPATH`-based approach to specifying
 which source files are used in a given build, and they are the default build
 mode in go1.16+. While this extension continues to support both Go modules and
-`GOPATH` mode, we highly recommend Go development in module mode. If you are
+`GOPATH` modes, we highly recommend Go development in module mode. If you are
 working on existing projects, please consider migrating to modules.
 
 Unlike the traditional `GOPATH` mode, module mode does not require the workspace
 to be located under `GOPATH` nor to use a specific structure. A module is
 defined by a directory tree of Go source files with a `go.mod` file in the
-tree's root directory. Your project may involve one or more modules. If you are
-working with multiple modules or uncommon project layouts, you will need to
-configure your workspace so that the extension knows which code to load, so that
-features like references can work across modules. Please see the
-for information on supported workspace layouts.
+tree's root directory.
+
+Your project may involve one or more modules. If you are working with multiple
+modules or uncommon project layouts, you will need to configure your workspace
+by using [Workspace Folders]. Please see this [documentation about supported
+workspace layouts].
 
 ## Customization
 
 The extension needs no configuration and should work out of the box. However,
-you may wish to adjust settings to customize its behavior. Below are a few
-commonly used settings. Please see the
+you may wish to adjust settings to customize its behavior. Please see the
 [settings documentation](docs/settings.md) for a comprehensive list of settings.
 See [advanced topics](docs/advanced.md) for further customizations and unique
 use cases.
 
+## Troubleshooting
+
+If the extension isn't working as you expect, you can take a look at our
+troubleshooting guides. There is one for [general
+troubleshooting](docs/troubleshooting.md), and another specifically for
+[troubleshooting the debugging feature](docs/debugging.md#troubleshooting).
+
 ## Ask for help
 
-If you're having issues with this extension, please reach out to us by
-[filing an issue](https://github.com/golang/vscode-go/issues/new/choose) or
-asking a question on the [Gophers Slack]. We hang out in the `#vscode` channel!
+If the troubleshooting guides did not resolve the issue, please reach out to us
+by [filing an issue](https://github.com/golang/vscode-go/issues/new/choose),
+[starting a GitHub discussion](https://github.com/golang/vscode-go/discussions),
+or by asking a question in the [Gophers Slack]. We hang out in the `#vscode`
+channel!
 
-Take a look at [learn.go.dev](https://learn.go.dev) and
+Also, you can take a look at [learn.go.dev](https://learn.go.dev) and
 [golang.org/help](https://golang.org/help) for more general guidance on using
 Go.
 
@@ -160,10 +161,10 @@ conduct-related issue, please mail [email protected].
 [Gophers Slack]: https://gophers.slack.com/
 [`gopls`]: https://golang.org/s/gopls
 [`go`]: https://golang.org/cmd/go
-[Manage extensions in VS Code]: https://code.visualstudio.com/docs/editor/extension-gallery
+[Managing extensions in VS Code]: https://code.visualstudio.com/docs/editor/extension-gallery
 [VS Code Go extension]: https://marketplace.visualstudio.com/items?itemName=golang.go
 [Go installation guide]: https://golang.org/doc/install
-[Go open source live video]: https://opensourcelive.withgoogle.com/events/go/watch?talk=session3
+[this video from the Go Open Source Live conference]: https://opensourcelive.withgoogle.com/events/go/watch?talk=session3
 [IntelliSense]: docs/features.md#intellisense
 [code navigation]: docs/features.md#code-navigation
 [code editing]: docs/features.md#code-editing
@@ -172,3 +173,6 @@ conduct-related issue, please mail [email protected].
 [debugging]: #debugging
 [full feature breakdown]: docs/features.md
 [workspace documentation]: https://github.com/golang/tools/blob/master/gopls/doc/workspace.md
+[`Go: Install/Update Go Tools` command]: docs/commands.md#go-installupdate-tools
+[documentation about supported workspace layouts]: https://github.com/golang/tools/blob/master/gopls/doc/workspace.md
+[Workspace Folders]: https://code.visualstudio.com/docs/editor/multi-root-workspaces