Add first steps to ISE compatibility doc

docs/ise_compatibility.md

@@ -0,0 +1,123 @@
+# ISE Compatibility
+
+While the PowerShell extension for VSCode does not seek
+complete feature parity with the PowerShell ISE,
+there are features in place to make the VSCode experience more natural
+for users of the ISE.
+
+This document tries to list settings you can configure in VSCode
+to make the user experience a bit more familiar compared to the ISE.
+
+## Key bindings
+
+| Function                              | ISE Binding                  | VSCode Binding                              |
+| ----------------                      | -----------                  | --------------                              |
+| Interrupt and break debugger          | <kbd>Ctrl</kbd>+<kbd>B</kbd> | <kbd>F6</kbd>                               |
+| Execute current line/highlighted text | <kbd>F8</kbd>                | <kbd>F8</kbd>                               |
+| List available snippets               | <kbd>Ctrl</kbd>+<kbd>J</kbd> | <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>J</kbd> |
+
+### Custom Keybindings
+
+You can [configure your own keybindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)
+in VSCode as well.
+
+## Tab completion
+
+To enable more ISE-like tab completion, add this setting:
+
+```json
+"editor.tabCompletion": "on"
+```
+
+This is a setting added directly to VSCode (rather than in the extension),
+so its behavior is determined by VSCode directly and cannot be changed by the extension.
+
+## No focus on console when executing
+
+To keep the focus in the editor when you execute with <kbd>F8</kbd>:
+
+```json
+"powershell.integratedConsole.focusConsoleOnExecute": false
+```
+
+The default is `true` for accessibility purposes.
+
+## Do not start integrated console on startup
+
+To stop the integrated console on startup, set:
+
+```json
+"powershell.integratedConsole.showOnStartup": false
+```
+
+**Note:** The background PowerShell process will still start,
+since that provides intellisense, script analysis, symbol navigation, etc.
+But the console will not be shown.
+
+## Assume files are PowerShell by default
+
+To make new/untitled files register as PowerShell by default:
+
+```json
+"files.defaultLanguage": "powershell"
+```
+
+## Color scheme
+
+There are a number of ISE themes available for VSCode
+to make the editor look much more like the ISE.
+
+In the [Command Palette]
+type `theme` to get `Preferences: Color Theme` and press <kbd>Enter</kbd>.
+In the drop down list, select `PowerShell ISE`.
+
+You can set this in the settings with:
+
+```json
+"workbench.colorTheme": "PowerShell ISE"
+```
+
+## PowerShell Command Explorer
+
+Thanks to the work of [@corbob](https://github.com/corbob),
+the PowerShell extension has the beginnings of its own command explorer.
+
+In the [Command Palette]
+enter `PowerShell Command Explorer` and press <kbd>Enter</kbd>.
+
+## Open in the ISE
+
+If you end up wanting to open a file in the ISE anyway,
+you can use <kbd>Shift</kbd>+<kbd>Alt</kbd>+<kbd>P</kbd>.
+
+## Other resources
+
+- 4sysops has [a great article](https://4sysops.com/archives/make-visual-studio-code-look-and-behave-like-powershell-ise/)
+  on configuring VSCode to be more like the ISE.
+- Mike F Robbins has [a really good post](https://mikefrobbins.com/2017/08/24/how-to-install-visual-studio-code-and-configure-it-as-a-replacement-for-the-powershell-ise/) on setting up VSCode.
+- Learn PowerShell has [an excellent write up](https://www.learnpwsh.com/setup-vs-code-for-powershell/)
+  on getting VSCode setup for PowerShell.
+
+## More settings
+
+If you know of more ways to make VSCode feel more familiar
+for ISE users, please contribute to this doc.
+If there's a compatibility configuration you're looking for,
+but you can't find any way to enable it,
+please [open an issue](https://github.com/PowerShell/vscode-powershell/issues/new/choose)
+and ask away!
+
+We are always happy to accept PRs and contributions as well!
+
+## VSCode Tips
+
+### Command Palette
+
+<kbd>F1</kbd> OR <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>
+(<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> on macOS)
+
+A handy way of executing commands in VSCode.
+See [the VSCode docs](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette)
+for more details.
+
+[Command Palette]: #command-palette

docs/troubleshooting.md

@@ -16,6 +16,22 @@ Instead syntax highlighting for VSCode, Atom, SublimeText and even GitHub is
 provided by the [Editor Syntax] repository on GitHub. Please open any
 [syntax highlighting issues there].
 
+## VSCode is not working like the ISE
+
+The PowerShell extension does not aim to perfectly recreate
+the experience of the PowerShell ISE.
+However, we do want to support compatibility whenever possible
+to do so without breaking existing functionality.
+
+Please see [the ISE compatibility doc](./ise_compatibility.md)
+for ways to configure VSCode to be closer to the ISE.
+
+Bear in mind that many of the UI/UX aspects of VSCode are driven by
+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
 
 - Highlighting/completions/command history don't work as I expect in the