diff --git a/README.md b/README.md
index 765e8760..eaf8b589 100644
--- a/README.md
+++ b/README.md
@@ -21,27 +21,36 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 ### Debug a script file
 Use this to launch your script file. Launch script file without waiting for debugger to attach.
 ```console
--m ptvsd --port 5678 myfile.py
+-m ptvsd --host localhost --port 5678 myfile.py
 ```
 If you want the debugger to attach before running your code use `--wait` flag.
 ```console
--m ptvsd --port 5678 --wait myfile.py
+-m ptvsd --host localhost  --port 5678 --wait myfile.py
 ```
+To attach from another machine, make sure that the server is listening on a public interface - using `0.0.0.0` will make it listen on all available interfaces:
+```console
+-m ptvsd --host 0.0.0.0 --port 5678 myfile.py
+```
+This should only be done on secure networks, since anyone who can connect to the specified port can then execute arbitrary code within the debugged process.
+
+To pass arguments to the script, just specify them after the filename. This works the same as with Python itself - everything up to  the filename is processed by ptvsd, but everything after that becomes `sys.argv` of the running process.
 
 ### Debug a module
 Use this to launch your module. Launch script file without waiting for debugger to attach.
 ```console
--m ptvsd --port 5678 -m mymodule
+-m ptvsd --host localhost --port 5678 -m mymodule
 ```
 If you want the debugger to attach before running your code use `--wait` flag.
 ```console
--m ptvsd --port 5678 --wait -m mymodule
+-m ptvsd --host localhost --port 5678 --wait -m mymodule
 ```
+Same as with scripts, command line arguments can be passed to the module by specifying them after the module name.
 
-### Debug a process by id
-Attach to a process running python code.
+
+### Attach to a running process by ID
+Injects the debugger into a process with a given PID that is running Python code. Once this command returns, a ptvsd server is running within the process, as if it were launched via `-m ptvd` itself.
 ```console
--m ptvsd --host 0.0.0.0 --port 5678 --pid 12345
+-m ptvsd --host localhost --port 5678 --pid 12345
 ```
 
 ## `ptvsd` Import usage
@@ -49,7 +58,6 @@ Attach to a process running python code.
 In your script import ptvsd and call `enable_attach` to enable the process to attach to the debugger. The default port is 5678. You can configure this while calling `enable_attach`. 
 ```python
 import ptvsd
-
 ptvsd.enable_attach()
 
 # your code
@@ -58,10 +66,8 @@ ptvsd.enable_attach()
 Use the `wait_for_attach()` function to block execution until debugger is attached.
 ```python
 import ptvsd
-
 ptvsd.enable_attach()
-# script execution will stop here till debugger is attached
-ptvsd.wait_for_attach()
+ptvsd.wait_for_attach() # script execution will stop here till debugger is attached
 
 # your code
 ```
@@ -70,7 +76,6 @@ ptvsd.wait_for_attach()
 In python >= 3.7, `ptvsd` supports the `breakpoint()` function. Use `break_into_debugger()` function for similar behavior and compatibility with older versions of python (2.7 and >= 3.4). These functions will block only if the debugger is attached.
 ```python
 import ptvsd
-
 ptvsd.enable_attach()
 
 while True:
@@ -81,7 +86,7 @@ while True:
 
 ## Custom Protocol arguments
 ### Launch request arguments
-```json
+```json5 
 {
     "debugOptions":  [
             "RedirectOutput",       // Whether to redirect stdout and stderr (see pydevd_comm.CMD_REDIRECT_OUTPUT)
@@ -98,7 +103,7 @@ while True:
 ```
 
 ### Attach request arguments
-```json
+```json5 
 {
     "debugOptions":  [
             "RedirectOutput",       // Whether to redirect stdout and stderr (see pydevd_comm.CMD_REDIRECT_OUTPUT)