[Ignore] Update troubleshooting.md and associated docs (#1541)

* Update and restructure README.md

* Update troubleshooting.md

* Info on opening an issue

* Update README to point at troubleshooting doc

* Update bug template to point to troubleshooting.md

* Suggest recording a GIF of bugs

* Use pasteable version expression in bug report

Author: rjmholt

.github/ISSUE_TEMPLATE/Bug_report.md

@@ -6,11 +6,8 @@ about: Report errors or unexpected behavior 🤔
 
 <!--
 
-BEFORE SUBMITTING A NEW ISSUE, PLEASE READ THE FAQ!!
-https://github.com/PowerShell/vscode-powershell/wiki/FAQ
-
-If your issue is not addressed by the FAQ, please
-fill in the following details so that we can help you!
+BEFORE SUBMITTING A NEW ISSUE, PLEASE READ THE TROUBLESHOOTING DOCS!
+https://github.com/PowerShell/vscode-powershell/tree/master/docs/troubleshooting.md
 
 IMPORTANT: you can generate a bug report directly from the
 PowerShell extension in Visual Studio Code by selecting
@@ -20,28 +17,55 @@ The more repro details you can provide, along with a zip
 of the log files from your session, the better the chances
 are for a quick resolution.
 
+You may also want to record a GIF of the bug occurring and
+attach it here by dropping the file into the description body.
+
 -->
 
 ### System Details
 
-- Operating system name and version:
-- VS Code version:
-- PowerShell extension version:
-- Output from `$PSVersionTable`:
+<!--
+To help diagnose your issue, the following details are helpful:
+- Operating system name and version
+- VS Code version
+- PowerShell extension version
+- Output from `$PSVersionTable`
+
+To get this information, run the following expression in your Integrated Console and paste the output here inside the backticks below:
+
+& {"### VSCode version: $(code -v)"
+"`n### VSCode extensions:`n$(code --list-extensions --show-versions | Out-String)"
+"`n### PSES version: $($pseditor.EditorServicesVersion)"
+"`n### PowerShell version:`n$($PSVersionTable | Out-String)"}
+
+
+If you are running VSCode Insiders, use this expression instead (and paste the result inside the backticks):
 
+& {"### VSCode version: $(code-insiders -v)"
+"`n### VSCode extensions:`n$(code-insiders --list-extensions --show-versions | Out-String)"
+"`n### PSES version: $($pseditor.EditorServicesVersion)"
+"`n### PowerShell version:`n$($PSVersionTable | Out-String)"}
+
+-->
+
+<!-- PowerShell output from above goes here -->
+System Details Output
 ```
-Copy / paste the following commands into the PowerShell Integrated Console, and paste the output here:
 
-code -v
-$pseditor.EditorServicesVersion
-code --list-extensions --show-versions
-$PSVersionTable
 ```
 
 ### Issue Description
 
 I am experiencing a problem with...
 
+#### Expected Behaviour
+
+-- Description of what *should* be happening --
+
+#### Actual Behaviour
+
+-- Description of what actually happens --
+
 ### Attached Logs
 
 Follow the instructions in the [README](https://github.com/PowerShell/vscode-powershell#reporting-problems)

README.md

@@ -8,9 +8,9 @@ that Visual Studio Code provides.
 
 ## Platform support
 
-- **Windows 7 through 10** with PowerShell v3 and higher
-- **Linux** with PowerShell v6 (all PowerShell-supported distributions)
-- **macOS and OS X** with PowerShell v6
+- **Windows 7 through 10** with Windows PowerShell v3 and higher, and PowerShell Core
+- **Linux** with PowerShell Core (all PowerShell-supported distributions)
+- **macOS and OS X** with PowerShell Core
 
 Read the [installation instructions](https://github.com/PowerShell/PowerShell/blob/master/docs/learning-powershell/using-vscode.md)
 to get more details on how to use the extension on these platforms.
@@ -26,11 +26,28 @@ Read the [FAQ](https://github.com/PowerShell/vscode-powershell/wiki/FAQ) for ans
 - Go to Definition of cmdlets and variables
 - Find References of cmdlets and variables
 - Document and workspace symbol discovery
-- Run selected selection of PowerShell code using `F8`
-- Launch online help for the symbol under the cursor using `Ctrl+F1`
+- Run selected selection of PowerShell code using <kbd>F8</kbd>
+- Launch online help for the symbol under the cursor using <kbd>Ctrl</kbd>+<kbd>F1</kbd>
 - Local script debugging and basic interactive console support!
 
-## Quick Installation
+## Installing the Extension
+
+You can install the official release of the PowerShell extension by following the steps
+in the [Visual Studio Code documentation](https://code.visualstudio.com/docs/editor/extension-gallery).
+In the Extensions pane, search for "PowerShell" extension and install it there.  You will
+get notified automatically about any future extension updates!
+
+You can also install a VSIX package from our [Releases page](https://github.com/PowerShell/vscode-powershell/releases) by following the
+[Install from a VSIX](https://code.visualstudio.com/docs/extensions/install-extension#_install-from-a-vsix)
+instructions.  The easiest way is through the command line:
+
+```
+code --install-extension PowerShell-<version>.vsix
+```
+
+> NOTE: If you are using VS Code Insiders, the command will be `code-insiders`.
+
+## Script-based Installation
 
 If you're on Windows 7 or greater with the [PowerShellGet](https://msdn.microsoft.com/powershell/gallery/readme)
 module installed, you can easily install both Visual Studio Code and the PowerShell
@@ -52,22 +69,14 @@ first before running it in this way!
 iex (iwr https://git.io/vbxjj)
 ```
 
-## Installing the Extension
-
-You can install the official release of the PowerShell extension by following the steps
-in the [Visual Studio Code documentation](https://code.visualstudio.com/docs/editor/extension-gallery).
-In the Extensions pane, search for "PowerShell" extension and install it there.  You will
-get notified automatically about any future extension updates!
-
-You can also install a VSIX package from our [Releases page](https://github.com/PowerShell/vscode-powershell/releases) by following the
-[Install from a VSIX](https://code.visualstudio.com/docs/extensions/install-extension#_install-from-a-vsix)
-instructions.  The easiest way is through the command line:
+## Reporting Problems
 
-```
-code --install-extension PowerShell-<version>.vsix
-```
+If you experience any problems with the PowerShell Extension, see
+[the troubleshooting docs](./docs/troubleshooting.md) for information
+on diagnosing and reporting issues.
 
-> NOTE: If you are using VS Code Insiders, the command will be `code-insiders`.
+#### Security Note
+For any security issues, please see [here](./docs/troubleshooting.md#note-on-security).
 
 ## Example Scripts
 
@@ -88,48 +97,6 @@ To open/view the extension's examples in Visual Studio Code, run the following f
 code (Get-ChildItem $Home\.vscode\extensions\ms-vscode.PowerShell-*\examples)[-1]
 ```
 
-## Reporting Problems
-
-If you're having trouble with the PowerShell extension, please follow these instructions
-to file an issue on our GitHub repository:
-
-### 1. File an issue on our [Issues Page](https://github.com/PowerShell/vscode-powershell/issues)
-
-Make sure to fill in the information that is requested in the issue template as it
-will help us investigate the problem more quickly.
-
-To automatically create a bug report from within the extension, open the Command pallet (<kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>) and run the *"Report a problem on GitHub"* command. Some basic information about your instance and powershell versions will be collected and inserted into a new GitHub issue.
-
-NOTE: If you believe that there is a security vulnerability in the PowerShell extension for VSCode,
-it **must** be reported to [[email protected]](https://technet.microsoft.com/security/ff852094.aspx) to allow for [Coordinated Vulnerability Disclosure](https://technet.microsoft.com/security/dn467923).
-**Only** file an issue, if [email protected] has confirmed filing an issue is appropriate.
-
-### 2. Capture verbose logs and send them to us
-
-If you're having an issue with crashing or other erratic behavior, add the following
-line to your User Settings in Visual Studio Code:
-
-```json
-    "powershell.developer.editorServicesLogLevel": "Verbose"
-```
-
-Restart Visual Studio Code and try to reproduce the problem.  Once you are done with
-that, zip up the logs in the corresponding folder for your operating system:
-
-- **Windows**: `$HOME\.vscode\extensions\ms-vscode.PowerShell-<CURRENT VERSION>\logs`
-- **Linux and macOS**: `~/.vscode/extensions/ms-vscode.PowerShell-<CURRENT VERSION>/logs`
-
-Alternatively, you can open the log folder using the Command pallet (<kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>) and running the *"Open powerShell Extension Logs Folder"* command.
-
-You have two options for sending us the logs:
-
-  1. If you are editing scripts that contain sensitive information (intellectual property,
-     deployment or administrative information, etc), e-mail the logs directly to
-     *[email protected]*.
-
-  2. If you are editing scripts that don't contain sensitive information, you can drag and
-     drop your logs ZIP file into the GitHub issue that you are creating.
-
 ## Contributing to the Code
 
 Check out the [development documentation](docs/development.md) for more details
@@ -139,7 +106,7 @@ on how to contribute to this extension!
 
 - [Keith Hill](https://github.com/rkeithhill) - [@r_keith_hill](http://twitter.com/r_keith_hill)
 - [Tyler Leonhardt](https://github.com/tylerl0706) - [@TylerLeonhardt](http://twitter.com/tylerleonhardt)
-- [David Wilson](https://github.com/daviwil) - [@daviwil](http://twitter.com/daviwil)
+- [Rob Holt](https://github.com/rjmholt)
 
 ## License
 

docs/development.md

@@ -5,25 +5,28 @@
 You'll need to clone two repositories and set up your development environment
 to before you can proceed.
 
-### 1. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [vscode-powershell repository](https://github.com/PowerShell/vscode-powershell)
+1. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [vscode-powershell repository](https://github.com/PowerShell/vscode-powershell)
 
-### 2. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [PowerShell Editor Services repository](https://github.com/PowerShell/PowerShellEditorServices)
+2. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [PowerShell Editor Services repository](https://github.com/PowerShell/PowerShellEditorServices)
 
-### 3. Follow the [development instructions](https://github.com/PowerShell/PowerShellEditorServices#development) for PowerShell Editor Services
+3. Follow the [development instructions](https://github.com/PowerShell/PowerShellEditorServices#development) for PowerShell Editor Services. **You will need to complete this step before proceeding**.
 
-### 4. Install [Visual Studio Code Insiders Release](https://code.visualstudio.com/insiders)
+4. Install the latest [Visual Studio Code Insiders release](https://code.visualstudio.com/insiders)
+    - You can also use the [standard Visual Studio Code release](https://code.visualstudio.com/). Both will work, but using VSCode
+    Insiders means the extension can be developed ready for new features
+    and changes in the next VSCode release.
 
-### 5. Install [Node.js](https://nodejs.org/en/) 6.0.0 or higher.
+5. Install [Node.js](https://nodejs.org/en/) 6.0.0 or higher.
 
 ## Building the Code
 
 #### From Visual Studio Code:
 
-Press <kbd>Ctrl+P</kbd> and type `task build`
+Press <kbd>Ctrl</kbd>+<kbd>P</kbd> and type `task build`
 
 This will compile the TypeScript files in the project to JavaScript files.
 
-#### From a command prompt:
+#### From a PowerShell prompt:
 
 ```
 Invoke-Build Build
@@ -34,7 +37,7 @@ Invoke-Build Build
 #### From Visual Studio Code:
 
 To debug the extension, press <kbd>F5</kbd>.  To run the extension without debugging,
-press <kbd>Ctrl+F5</kbd> or <kbd>Cmd+F5</kbd> on macOS.
+press <kbd>Ctrl</kbd>+<kbd>F5</kbd> or <kbd>Cmd</kbd>+<kbd>F5</kbd> on macOS.
 
 #### From a command prompt: