Merge FAQ into troubleshooting guide

Author: andyleejordan

docs/troubleshooting.md

@@ -3,13 +3,21 @@
 This document contains troubleshooting steps for commonly reported issues when using the
 [PowerShell Extension] for Visual Studio Code.
 
-## Script Analysis is Reporting False Errors
+## How do I debug my PowerShell script?
 
-Script analysis is provided by the [PSScriptAnalyzer] project on GitHub.
-Please [open an issue there] if you are getting fault script diagnostics
-(red and green squiggly lines under PowerShell in scripts).
+This topic is best covered in the "Debugging PowerShell Script in Visual Studio Code"
+Scripting Guys blog posts (thanks community!):
 
-## Problems with Syntax Highlighting
+* [Part 1](https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/06/debugging-powershell-script-in-visual-studio-code-part-1/)
+* [Part 2](https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/13/debugging-powershell-script-in-visual-studio-code-part-2/)
+
+## Script analysis is reporting false errors
+
+Script analysis is provided by the [PSScriptAnalyzer] project on GitHub. If the warning
+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].
+
+## Problems with syntax highlighting
 
 PowerShell syntax highlighting is not performed by the [PowerShell Extension].
 Instead syntax highlighting for VSCode, Atom, SublimeText and even GitHub is
@@ -30,7 +38,19 @@ were, set:
 If you leave it enabled, you can customize the colors used for the various
 tokens. See [#3221] for more info and to leave suggestions.
 
-## VSCode is not working like the ISE
+## PSReadline features aren't working
+
+Integration of [PSReadline] into the PowerShell Integrated Console is under active
+development, so some features (like history recall) don't yet work. Additionally, the
+terminal itself is a custom PowerShell host implementation and is far from perfect.
+
+## Windows aren't appearing
+
+Due to an [issue](https://github.com/Microsoft/vscode/issues/42356) in Electron, windows
+spawned by Visual Studio Code (such as those for `Get-Credential`, `Connect-MsolService`,
+`Connect-AzAccount`, `Connect-AzureAd`, etc.) do not appear above Visual Studio Code.
+
+## Visual Studio Code is not working like the ISE
 
 The PowerShell extension does not aim to perfectly recreate
 the experience of the PowerShell ISE.
@@ -45,7 +65,7 @@ VSCode itself and can't be changed by the extension.
 The VSCode maintainers are quite reasonable though,
 and you can ask for new features [in their repository](https://github.com/Microsoft/vscode).
 
-## Known Issues in the Extension
+## Known issues in the extension
 
 - If you are running the Preview version "PowerShell Preview" side-by-side with the stable version "PowerShell"
   you will experience performance and debug issues.
@@ -84,7 +104,7 @@ and you can ask for new features [in their repository](https://github.com/Micros
     may be opportunities to improve our integration with it in the
     [PowerShell Extension] too.
 
-## Reporting an Issue
+## Reporting an issue
 
 If you experience a problem with the [PowerShell Extension]:
 
@@ -97,7 +117,7 @@ If you experience a problem with the [PowerShell Extension]:
    [look there].
 3. If you don't see the issue you're experiencing, please [open a new issue].
 
-## Opening a New Issue
+## Opening a new issue
 
 If you experience an issue with the [PowerShell Extension] and can't find
 an existing issue for it, [open an issue on us on GitHub].
@@ -118,7 +138,7 @@ When opening an issue, keep in mind:
   [tackling an issue], we always accept contributions and will help you
   at every step.
 
-## Reproducing the Issue
+## Reproducing the issue
 
 To fix the issue, we need to be able to reproduce it.
 To do that, we need:
@@ -134,7 +154,7 @@ the GitHub issue template will have sections
 to guide you through providing all of this information
 as well as environment information discussed below.
 
-## Providing Information About Your Environment
+## Providing information about your environment
 
 For solving most issues, the following information is important to provide:
 
@@ -213,7 +233,7 @@ At this point, you may delete the setting if you want.
   vscode-powershell@microsoft.com. Please still open an issue though
   so we can track the work — other users may have the same issue.
 
-### Visual Studio Code Version
+### Visual Studio Code version
 
 [Your VSCode version] can be obtained from the Integrated Console
 or PowerShell like this:
@@ -245,7 +265,7 @@ code: The term 'code' is not recognized as the name of a cmdlet, ...
 in this case, use the file menu in VSCode and choose `Help`>`About`
 (or `Code`>`About Visual Studio Code` on macOS) to get version information.
 
-### PowerShell Extension Version
+### PowerShell extension version
 
 [Your installed PowerShell Extension version] can similarly be found with:
 
@@ -278,7 +298,8 @@ If VSCode isn't on your path use the [Command Palette]
 (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>) to enter
 `Extensions: Show Installed Extensions` and list your extensions.
 
-### Editor Services Version
+### Editor Services version
+
 To get the [PowerShell Editor Services] version, in the Integrated
 Console, enter:
 
@@ -289,7 +310,8 @@ Major  Minor  Build  Revision
 1      8      4      0
 ```
 
-### PowerShell Version Table
+### PowerShell version table
+
 You can get [your PowerShell version table] from the Integrated Console:
 
 ```powershell
@@ -307,7 +329,7 @@ SerializationVersion           1.1.0.1
 WSManStackVersion              3.0
 ```
 
-### Operating System Information
+### Operating system information
 
 - Windows - all needed information should already be in the `$PSVersionTable`
 - macOS
@@ -316,7 +338,7 @@ WSManStackVersion              3.0
   - `uname -a`
   - Your distro and version (usually `lsb_release -a` is the best here)
 
-### Note on Security
+### Note on security
 
 If you believe there is a security vulnerability in the [PowerShell Extension]
 (or in [PowerShell Editor Services]), it **must** be reported directly to