diff --git a/docs/ise_compatibility.md b/docs/ise_compatibility.md
new file mode 100644
index 0000000000..67ad6fd973
--- /dev/null
+++ b/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 | Ctrl+B | F6 |
+| Execute current line/highlighted text | F8 | F8 |
+| List available snippets | Ctrl+J | Ctrl+Alt+J |
+
+### 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 F8:
+
+```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 Enter.
+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 Enter.
+
+## Open in the ISE
+
+If you end up wanting to open a file in the ISE anyway,
+you can use Shift+Alt+P.
+
+## 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
+
+F1 OR Ctrl+Shift+P
+(Cmd+Shift+P 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
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 7256d43592..b5a50ff2c5 100644
--- a/docs/troubleshooting.md
+++ b/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