diff --git a/README.md b/README.md
index a7519e8..8475ab2 100644
--- a/README.md
+++ b/README.md
@@ -125,7 +125,7 @@ And a couple of brief demos:
 - locals and globals display
 - watch expressions with autocompletion
 - call stack display and navigation
-- variable value display hover
+- hierarchical variable value display popup (see `<Plug>VimspectorBalloonEval`)
 - interactive debug console with autocompletion
 - launch debugee within Vim's embedded terminal
 - logging/stdout display
@@ -231,8 +231,8 @@ Why such a new vim ? Well 2 reasons:
    if you hit them.
 
 Why is neovim experimental? Because the author doesn't use neovim regularly, and
-there are no regression tests for vimspector in neovim, so it's likely to break
-frequently.  Issue reports are handled on best-efforts basis, and PRs are
+there are no regression tests for vimspector in neovim, so it may break
+occasionally. Issue reports are handled on best-efforts basis, and PRs are
 welcome to fix bugs. See also the next section descibing differences for neovim
 vs vim.
 
@@ -250,7 +250,8 @@ neovim doesn't implement some features Vimspector relies on:
   the output window's current output.
 * Prompt Buffers - used to send commands in the Console and add Watches.
   (*Note*: prompt buffers are available in neovim nightly)
-* Tooltips - used to display the values of variables when debugging.
+* Balloons - this allows for the variable evaluation popup to be displayed when
+  hovering the mouse. See below for how to create a keyboard mapping instead.
 
 Workarounds are in place as follows:
 
@@ -259,9 +260,18 @@ Workarounds are in place as follows:
   [`:VimspectorReset`](#closing-debugger)
 * Prompt Buffers - There are [`:VimspectorEval`](#console)
   and [`:VimspectorWatch`](#watches)
-* Functions - There are
-  [`:call vimspector#ShowTooltip()`](#variable-or-selection-hover-evaluation) and
-  [`:call vimspector#ShowTooltipForSelection()`](#variable-or-selection-hover-evaluation)
+* Balloons - There is the `<Plug>VimspectorBalloonEval` mapping. There is no
+default mapping for this, so I recommend something like this to get variable
+display in a popup:
+
+```viml
+" mnemonic 'di' = 'debug inspect' (pick your own, if you prefer!)
+
+" for normal mode - the word under the cursor
+nmap <Leader>di <Plug>VimspectorBalloonEval
+" for visual mode, the visually selected text
+xmap <Leader>di <Plug>VimspectorBalloonEval
+```
 
 ## Windows differences
 
@@ -654,6 +664,7 @@ features to set your own mappings. To that end, Vimspector defines the following
 * `<Plug>VimspectorStepInto`
 * `<Plug>VimspectorStepOut`
 * `<Plug>VimspectorRunToCursor`
+* `<Plug>VimspectorBalloonEval`
 
 These map roughly 1-1 with the API functions below.
 
@@ -716,6 +727,18 @@ let g:vimspector_enable_mappings = 'HUMAN'
 | `F11`        | Step Into                                                 | `vimspector#StepInto()`                                      |
 | `F12`        | Step out of current function scope                        | `vimspector#StepOut()`                                       |
 
+In addition, I recommend adding a mapping to `<Plug>VimspectorBalloonEval`, in
+normal and visual modes, for example:
+
+```viml
+" mnemonic 'di' = 'debug inspect' (pick your own, if you prefer!)
+
+" for normal mode - the word under the cursor
+nmap <Leader>di <Plug>VimspectorBalloonEval
+" for visual mode, the visually selected text
+xmap <Leader>di <Plug>VimspectorBalloonEval
+```
+
 # Usage and API
 
 This section defines detailed usage instructions, organised by feature. For most
@@ -894,13 +917,16 @@ Scopes and variables are represented by the buffer `vimspector.Variables`.
 ## Variable or selection hover evaluation
 
 All rules for `Variables and scopes` apply plus the following:
+
 * With mouse enabled, hover over a variable and get the value it evaluates to.
-* Use your mouse to perform a visual selection of an expression (e.g. `a + b`) and get its result.
-* Call `vimspector#ShowTooltip()` or `vimspector#ShowTooltipForSelection()` to evaluate expressions without mouse (the only way to use this feature in nvim).
-* Use regular nagivation keys to chose the current selection; `<Esc>` (or leave the tooltip window) to close the tooltip.
-
-Note: using a selection evaluation might lead to undesired consequences, since **the expression is actually executed**. E.g. `c = a + b;` once this entire line is evaluated, value of `c` becomes the sum of `a` and `b`.
+* Use your mouse to perform a visual selection of an expression (e.g. `a + b`)
+  and get its result.
+* Make a normal mode (`nmap`) and visual mode (`xmap`) mapping to
+  `<Plug>VimspectorBalloonEval` to manually trigger the popup.
+* Use regular nagivation keys (`j`, `k`) to chose the current selection; `<Esc>`
+  (or leave the tooltip window) to close the tooltip.
 
+![variable eval hover](https://puremourning.github.io/vimspector-web/img/vimspector-variable-eval-hover.png)
 
 ## Watches