diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6aede91fc0fc..04abf6a0df58 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@
 
 ### Prerequisites
 
-1. Node.js (>= 8.9.1, < 9.0.0)
+1. Node.js (>= 8.9.1, < 9.0.0), and [Yarn](https://yarnpkg.com/lang/en/docs/install/)
 2. Python 2.7 or later (required only for testing the extension and running unit tests)
 3. Windows, OS X or Linux
 4. Visual Studio Code
@@ -20,6 +20,8 @@ cd vscode-python
 yarn install
 ```
 
+You may see warnings that ```The engine "vscode" appears to be invalid.```, you can ignore these.
+
 ### Incremental Build
 
 Run the `Compile` and `Hygiene` build Tasks from the [Command Palette](https://code.visualstudio.com/docs/editor/tasks) (short cut `CTRL+SHIFT+B` or `⇧⌘B`)
diff --git a/README.md b/README.md
index cd17a9f93100..c8d3639b7b7b 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,49 @@
 # Python extension for Visual Studio Code
 
-A [Visual Studio Code](https://code.visualstudio.com/) [extension](https://marketplace.visualstudio.com/VSCode) with rich support for the [Python language](https://www.python.org/) (_including Python 3.6_), with features including the following and more:
-* Linting ([Prospector](https://pypi.io/project/prospector/), [Pylint](https://pypi.io/project/pylint/), [pycodestyle](https://pypi.io/project/pycodestyle/), [Flake8](https://pypi.io/project/flake8/), [pylama](https://github.com/klen/pylama), [pydocstyle](https://pypi.io/project/pydocstyle/), [mypy](http://mypy-lang.org/) with config files and plugins)
-* Intellisense (autocompletion with support for PEP 484 and PEP 526)
-* Auto indenting
-* Code formatting ([autopep8](https://pypi.io/project/autopep8/), [yapf](https://pypi.io/project/yapf/), with config files)
-* Code refactoring (Rename, Extract Variable, Extract Method, Sort Imports)
-* Viewing references, code navigation, view signature
-* Excellent debugging support (remote debugging over SSH, mutliple threads, django, flask)
-* Running and debugging Unit tests ([unittest](https://docs.python.org/3/library/unittest.html#module-unittest), [pytest](https://pypi.io/project/pytest/), [nose](https://pypi.io/project/nose/), with config files)
-* Execute file or code in a python terminal
-* Snippets
+A [Visual Studio Code](https://code.visualstudio.com/) [extension](https://marketplace.visualstudio.com/VSCode) with rich support for the [Python language](https://www.python.org/) (_including Python 3.6_), including features such as linting, debugging, IntelliSense, code navigation, code formatting, refactoring, unit tests, snippets, and more!
+
+## Quick start
+
+* **Step 1.** [Install a supported version of Python on your system](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites) (note: that the system install of Python on macOS is not supported).
+* **Step 2.** Install the Python extension for Visual Studio Code.
+* **Step 3.** Open or create a Python file and start coding!
+
+## Optional steps
+* **Step 4.** [Install a linter](https://code.visualstudio.com/docs/python/linting) to get errors and warnings -- you can further customize linting rules to fit your needs.
+* **Step 5.** Select your preferred Python interpreter/version/environment using the `Select Interpreter` command.
+  + By default we use the one that's on your path.
+  + If you have a workspace open you can also click in the status bar to change the interpreter.
+* **Step 6.** Install `ctags` for Workspace Symbols, from [here](http://ctags.sourceforge.net/), or using `brew install ctags` on macOS.
 
-## Quick Start
+For more information you can:
+* [Follow our Python tutorial](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites) with step-by-step instructions for building a simple app.
+* Check out the [Python documentation on the VS Code site](https://code.visualstudio.com/docs/languages/python) for general information about using the extension.
 
-* Install the extension
-* optionally install `ctags` for Workspace Symbols, from [here](http://ctags.sourceforge.net/), or using `brew install ctags` on macOS
-* Select your Python interpreter
-  + If it's already in your path then you're set
-  + Otherwise, to select a different Python interpreter/version/environment (use the command `Select Workspace Interpreter` or look in the status bar)
+## Useful commands
 
-## [Documentation](https://code.visualstudio.com/docs/languages/python)
+Open the Command Palette (Command+Shift+P on macOS and Ctrl+Shift+P on Windows/Linux) and type in one of the following commands:
 
-For further information and details continue through to the [documentation](https://code.visualstudio.com/docs/languages/python).
+Command | Description
+--- | ---
+```Python: Select Interpreter``` | Switch between Python interpreters, versions, and environments.
+```Python: Start REPL``` | Start an interactive Python REPL using the selected interpreter in the VS Code terminal.
+```Python: Run Python File in Terminal``` | Runs the active Python file in the VS Code terminal. You can also run a Python file by right-clicking on the file and selecting ```Run Python File in Terminal```.
+```Python: Select Linter``` | Switch from PyLint to flake8 or other supported linters.
 
-## Questions, Issues, Feature Requests, and Contributions
+To see all available Python commands, open the Command Palette and type ```Python```.
+
+## Supported locales
+
+The extension is available in multiple languages thanks to external
+contributors (if you would like to contribute a translation, see the
+[pull request which added simplified Chinese](https://github.com/Microsoft/vscode-python/pull/240)):
+
+* `en`
+* `ja`
+* `ru`
+* `zh-cn`
+
+## Questions, issues, feature requests, and contributions
 
 * If you have a question about how to accomplish something with the extension, please [ask on Stack Overflow](https://stackoverflow.com/questions/tagged/visual-studio-code+python)
 * If you come across a problem with the extension, please [file an issue](https://github.com/microsoft/vscode-python)
@@ -33,15 +52,15 @@ For further information and details continue through to the [documentation](http
   - If someone has already [file an issue](https://github.com/Microsoft/vscode-python) that encompasses your feedback, please leave a 👍/👎 reaction on the issue
   - Otherwise please file a new issue
 
-## Feature Details
+## Feature details
 
-* IDE-like Features
+* IDE-like features
   + Automatic indenting
   + Code navigation ("Go to", "Find all" references)
   + Code definition (Peek and hover definition, View signatures)
   + Rename refactoring
   + Sorting import statements (use the `Python: Sort Imports` command)
-* Intellisense and Autocomplete (including PEP 484 support)
+* Intellisense and autocomplete (including PEP 484 and PEP 526 support)
   + Ability to include custom module paths (e.g. include paths for libraries like Google App Engine, etc.; use the setting `python.autoComplete.extraPaths = []`)
 * Code formatting
   + Auto formatting of code upon saving changes (default to 'Off')
@@ -50,19 +69,19 @@ For further information and details continue through to the [documentation](http
   + Support for multiple linters with custom settings (default is [Pylint](https://pypi.io/project/pylint/), but [Prospector](https://pypi.io/project/prospector/), [pycodestyle](https://pypi.io/project/pycodestyle/), [Flake8](https://pypi.io/project/flake8/), [pylama](https://github.com/klen/pylama), [pydocstyle](https://pypi.io/project/pydocstyle/), and [mypy](http://mypy-lang.org/) are also supported)
 * Debugging
   + Watch window
-  + Evaluate Expressions
+  + Evaluate expressions
   + Step through code ("Step in", "Step out", "Continue")
-  + Add/remove break points
+  + Add/remove breakpoints
   + Local variables and arguments
   + Multi-threaded applications
   + Web applications (such as [Flask](http://flask.pocoo.org/) & [Django](https://www.djangoproject.com/), with template debugging)
   + Expanding values (viewing children, properties, etc)
-  + Conditional break points
+  + Conditional breakpoints
   + Remote debugging (over SSH)
   + Google App Engine
   + Debugging in the integrated or external terminal window
   + Debugging as sudo
-* Unit Testing
+* Unit testing
   + Support for [unittest](https://docs.python.org/3/library/unittest.html#module-unittest), [pytest](https://pypi.io/project/pytest/), and [nose](https://pypi.io/project/nose/)
   + Ability to run all failed tests, individual tests
   + Debugging unit tests
@@ -70,10 +89,10 @@ For further information and details continue through to the [documentation](http
 * Miscellaneous
   + Running a file or selected text in python terminal
 * Refactoring
-  + Rename Refactorings
-  + Extract Variable Refactorings
-  + Extract Method Refactorings
-  + Sort Imports
+  + Rename refactorings
+  + Extract variable refactorings
+  + Extract method refactorings
+  + Sort imports
 
 ![General Features](https://raw.githubusercontent.com/microsoft/vscode-python/master/images/general.gif)
 
@@ -82,18 +101,9 @@ For further information and details continue through to the [documentation](http
 ![Unit Tests](https://raw.githubusercontent.com/microsoft/vscode-python/master/images/unittest.gif)
 
 
-## Supported locales
-
-The extension is available in multiple languages thanks to external
-contributors (if you would like to contribute a translation, see the
-[pull request which added simplified Chinese](https://github.com/Microsoft/vscode-python/pull/240)):
 
-* `en`
-* `ja`
-* `ru`
-* `zh-cn`
 
-## Data/Telemetry
+## Data and telemetry
 
 The Microsoft Python Extension for Visual Studio Code collects usage
 data and sends it to Microsoft to help improve our products and