Include $ in PowerShell word separators

Add to troubleshooting guide how to modify this behavior and the reasoning
behind the suggestions.

Author: andyleejordan

docs/troubleshooting.md

@@ -17,6 +17,46 @@ Script analysis is provided by the [PSScriptAnalyzer] project on GitHub. If the
 message starts with `[PSScriptAnalyzer]` or if you are getting faulty script diagnostics
 (red and green squiggly lines under PowerShell in scripts) please [open an issue there].
 
+## Double-click isn't selecting the whole variable
+
+Visual Studio Code provides a default set of word separators, that is,
+characters that split words and so affect double-click selections. The editor's
+defaults include both `-` and `$`. In [v2021.5.1] we starting providing a
+default value for PowerShell files that excludes these two symbols. The
+intention of this change was to increase predictability, as double-clicking
+PowerShell symbols would now select the same portion that the extension
+highlights (with the exception of scoped variables due to the continued
+inclusion of `:` as a word separator) as well as align with collected user
+feedback.
+
+We excluded `-` because unlike programming languages that use `CamelCase` or
+`snake_case`, PowerShell uses a `Verb-Noun` style where dashes are part of many
+symbol names (like underscores in other languages). So by excluding it we teach
+Visual Studio Code to treat `Verb-Noun` as one symbol/word, which matches what
+the extension semantically highlights when the cursor is placed within it.
+
+We originally excluded `$` because PowerShell uses it as a prefix for variable
+substition, and many users were already excluding it. This change proved
+controversial and so after reviewing even more user feedback after the public
+rollout of this change, we've decided to compromise among varying user desires
+by continuing to exclude `-` but revert the exclusion of `$`.
+
+You can reset the behavior for PowerShell files to Visual Studio Code defaults
+with the following code added to `settings.json`:
+
+```json
+"[powershell]": {
+    "editor.wordSeparators": "`~!@#$%^&*()-=+[{]}\\|;:'\",.<>/?"
+}
+```
+
+Similarly you can edit this setting to exclude `$` just by removing it from the
+string, and if you do so, double-clicking `$MyVariable` will then select the
+whole symbol, matching what the extension semantically highlights, instead of
+just `MyVariable`. Keeping `-` will cause double-clicking `Verb-Noun` to only
+select the part of the symbol on the side of the `-` that you clicked. These
+settings are personal preferences.
+
 ## Problems with syntax highlighting
 
 PowerShell syntax highlighting is performed in combintation by the [PowerShell Extension]
@@ -366,6 +406,7 @@ an issue on GitHub is appropriate.
 [semantic highlighting]: https://code.visualstudio.com/api/language-extensions/semantic-highlight-guide
 [tackling an issue]: ./development.md
 [v2021.2.2]: https://github.com/PowerShell/vscode-powershell/releases/tag/v2021.2.2
+[v2021.5.1]: https://github.com/PowerShell/vscode-powershell/releases/tag/v2021.5.1
 [VSCode issue]: https://github.com/Microsoft/vscode/issues/42356
 [VSCode Settings]: https://code.visualstudio.com/docs/getstarted/settings
 [will break this compatibility]: https://github.com/PowerShell/vscode-powershell/issues/1310

package.json

@@ -899,7 +899,7 @@
       "[powershell]": {
         "debug.saveBeforeStart": "nonUntitledEditorsInActiveGroup",
         "editor.semanticHighlighting.enabled": false,
-        "editor.wordSeparators": "`~!@#%^&*()=+[{]}\\|;:'\",.<>/?"
+        "editor.wordSeparators": "`~!@#$%^&*()=+[{]}\\|;:'\",.<>/?"
       }
     },
     "themes": [