diff --git a/README.org b/README.org
index 50f49b3c..68b3fd9e 100644
--- a/README.org
+++ b/README.org
@@ -8,6 +8,7 @@
 - [[#dap-mode][dap-mode]]
   - [[#summary][Summary]]
     - [[#project-status][Project status]]
+  - [[#Install][Install]]
   - [[#usage][Usage]]
   - [[#features][Features]]
   - [[#configuration][Configuration]]
@@ -23,6 +24,37 @@
 *** Project status
    The API considered unstable until 1.0 release is out. It is tested against
    Java, Python, Ruby, Elixir and LLDB (C/C++/Objective-C/Swift).
+** Install
+   There are several ways to install ~dap-mode~.
+*** ~package.el~
+    To use the native Emacs package manager, ~package.el~, first add
+    [[https://melpa.org][MELPA]] or [[https://stable.melpa.org/][MELPA Stable]] to the ~package-archive~ alist:
+
+    #+begin_src elisp
+    (require 'package)
+    (add-to-list 'package-archives
+                 '("melpa-stable" . "https://stable.melpa.org/packages/"))
+    #+end_src
+
+    Next,
+    - ~M-x package-refresh-contents~ to refresh the package listing
+    - ~M-x package-install RET dap-mode RET~ to install ~dap-mode~
+
+    Finally, load Emacs Lisp packages and enable ~dap-mode~:
+
+    #+begin_src elisp
+    (package-initialize)
+    (dap-mode 1)
+    #+end_src
+*** [[https://github.com/jwiegley/use-package][~use-package.el~]]
+    For users of ~use-package~, install and enable ~dap-mode~ with:
+
+    #+begin_src elisp
+    (use-package dap-mode
+      :ensure t
+      :init
+      (dap-mode 1))
+    #+end_src
 ** Usage
   The main entry points are ~dap-debug~ and ~dap-debug-edit-template~. The first
   one asks for a registered debug template and starts the configuration using
diff --git a/docs/page/configuration.md b/docs/page/configuration.md
index 09113ad1..b64aecf0 100644
--- a/docs/page/configuration.md
+++ b/docs/page/configuration.md
@@ -1,9 +1,16 @@
 Configuration
 ===============
 
+After [installing
+`dap-mode`](https://github.com/emacs-lsp/dap-mode#Install), you may
+need to install a DAP compliant debugger.  `dap-mode` will need to be
+configured to connect with it.  This most easily done with
+`dap-auto-configure-mode`.
+
 ## DAP mode configuration
 
-For an auto-configuration enable the `dap-auto-configure-mode`. You can configure which features from `dap-mode` do you want with `dap-auto-configure-features`:
+
+You can configure which features from `dap-mode` do you want with `dap-auto-configure-features`:
 
 ```elisp
 ;; Enabling only some features
@@ -77,26 +84,40 @@ settings.
 
 1.  Installation
 
-      - install latest version of ptvsd.
+    A Python DAP compliant debugger is provided by `debugpy`.  This
+    can be installed with:
 
-        ``` bash
-        pip install "ptvsd>=4.2"
-        ```
+    ``` bash
+    pip install "debugpy"
+    ```
 
-          - Then add the following line in your config:
+    Use the following to load Python configurations into `dap-debug`:
 
-            ``` elisp
-            (require 'dap-python)
-            ```
+    ``` elisp
+    (require 'dap-python)
+    ```
+
+    Use `dap-python-debugger` to specify which debugger to use.
 
-        This will add the python related configuration to `dap-debug`.
+    For example,
+
+    ``` elisp
+    (use-package dap-mode
+        :config
+        (require 'dap-python)
+        (setq dap-python-debugger 'debugpy))
+    ```
 
 2.  Usage
 
-    A template named "Python :: Run Configuration" will appear, which
-    will execute the currently visited module. This will fall short
-    whenever you need to specify arguments, environment variables or
-    execute a setuptools based script. In such case, define a template:
+    If using a virtual environment, make sure it is activated.  Next,
+    call `dap-auto-configure-mode`.  Use `dap-debug` when you are
+    ready to debug.  You are able to choose from various Run
+    Configurations (e.g. `Python :: Run file (buffer)`) which specify
+    debug parameters.  Press `<tab>` to see available templates.
+
+    You can specify arguments, environment variables or execute a
+    setuptools based script, with a custom template:
 
     ``` elisp
     (dap-register-debug-template "My App"
@@ -109,6 +130,9 @@ settings.
             :name "My App"))
     ```
 
+    Templates can be quickly created and modified using
+    `dap-debug-edit-template`.
+
 ## Ruby
 
   - Download and extract [VSCode Ruby