diff --git a/doc/ale.txt b/doc/ale.txt
index 6fc8367b..932c96b8 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -668,14 +668,11 @@ at the cursor taken from LSP linters. The following commands are supported:
 
 |ALEHover| - Print information about the symbol at the cursor.
 
-If |b:ale_set_balloons| is set and you are are using vim with the
-|balloon_show()| feature (tested with vim 8 patch 1318), then "hover"
-information also show up when you put the mouse on a symbol in a buffer
-("mouseover").
-Diagnostics information have priority over hover information for the balloon
-space : if there is a diagnostics message (warning or error) on the line the
-mouse points to, then the mouseover will print this information instead of
-hover information.
+If |b:ale_set_balloons| is set to `1` and your version of Vim supports the
+|balloon_show()| function, then "hover" information also show up when you move
+the mouse over a symbol in a buffer. Diagnostic information will take priority
+over hover information for balloons. If a line contains a problem, that
+problem will be displayed in a balloon instead of hover information.
 
 
 ===============================================================================
@@ -1349,20 +1346,23 @@ g:ale_set_balloons                                         *g:ale_set_balloons*
                                                            *b:ale_set_balloons*
 
   Type: |Number|
-  Default: `has('balloon_eval') && has('gui_running') ||`
-           `has('balloon_eval_term') && !has('gui_running')`
+  Default: `(has('balloon_eval') && has('gui_running'))`
+           `|| (has('balloon_eval_term') && !has('gui_running'))`
 
   When this option is set to `1`, balloon messages will be displayed for
-  problems or hover information if relevant. Problems nearest to the cursor on
-  the line the cursor is over will be displayed. If there are no problem, and
-  one of the linters support |ale-hover|, then brief information about the
-  symbol under the cursor will be shown. Balloons will not be shown when
-  either |g:ale_enabled| is `0` or |b:ale_enabled| is `0`.
+  problems or hover information if available.
+
+  Problems nearest to the line the mouse cursor is over will be displayed. If
+  there are no problems to show, and one of the linters is an LSP linter
+  supporting "Hover" information, per |ale-hover|, then brief information
+  about the symbol under the cursor will be displayed in a balloon.
 
   `b:ale_set_balloons` can be set to `0` to disable balloons for a buffer.
   Balloons cannot be enabled for a specific buffer when not initially enabled
   globally.
 
+  Balloons will not be shown when |g:ale_enabled| or |b:ale_enabled| is `0`.
+
 
 g:ale_set_balloons_legacy_echo                 *g:ale_set_balloons_legacy_echo*
                                                *b:ale_set_balloons_legacy_echo*