diff --git a/README.asciidoc b/README.asciidoc
index fc1b6e13..4c5b6099 100644
--- a/README.asciidoc
+++ b/README.asciidoc
@@ -820,9 +820,14 @@ Options are typed, their type can be
  * `{int,str}-list`: a list, elements are separated by a colon (:)
   if an element needs to contain a colon, it can be escaped with a
   backslash.
- * `range-faces`: a list, elements are separated by a colon (:), of
-  a buffer range (<begin line>.<begin column>,<end line>.<end column>)
-  and a face (separated by `|`)
+ * `range-faces`: a `:` separated list of a pairs of a buffer range
+   (`<begin line>.<begin column>,<end line>.<end column>`) and  a face
+   (separated by `|`), except for the first element which is just the
+   timestamp of the buffer.
+ * `completions`: a `:` separated list of `<text>|<docstring>|<menu text>`
+   candidates, except for the first element which follows the
+   `<line>.<column>[+<length>]@<timestamp>` format to define where the
+   completion apply in the buffer.
  * `enum(value1|value2|...)`: an enum, taking on of the given values
  * `flags(value1|value2|...)`: a set of flags, taking a combination
    of the given values joined by `|`.
@@ -893,10 +898,7 @@ Some options are built in Kakoune, and can be used to control it's behaviour:
      (`word=all`) or only the current one (`word=buffer`)
    - `filename` which tries to detect when a filename is being entered and
      provides completion based on local filesystem.
-   - `option=<opt-name>` where <opt-name> is a _completions_ option, which is a `:`
-     separated list of _<text>|<docstring>|<menu text>_ candidates, except for the first
-     element which follows the _<line>.<column>[+<length>]@<timestamp>_ format to define
-     where the completion apply in the buffer.
+   - `option=<opt-name>` where <opt-name> is a _completions_ option.
  * `static_words` _str-list_: list of words that are always added to completion
      candidates when completing words in insert mode.
  * `completions_extra_word_chars` _str_: a string containing all additional character
diff --git a/doc/manpages/options.asciidoc b/doc/manpages/options.asciidoc
index 4e44b0a8..405336d1 100644
--- a/doc/manpages/options.asciidoc
+++ b/doc/manpages/options.asciidoc
@@ -23,9 +23,15 @@ Types
 	to contain a colon, it can be escaped
 	with a backslash
 *range-faces*::
-	a list, elements are separated by a colon (:), of pairs of buffer
-	range (`<begin line>.<begin column>,<end line>.<end column>`) and
-	face (separated by `|`)
+	a `:` separated list of a pairs of a buffer range
+	(`<begin line>.<begin column>,<end line>.<end column>`) and  a face
+	(separated by `|`), except for the first element which is just the
+	timestamp of the buffer.
+*completions*::
+	a `:` separated list of `<text>|<docstring>|<menu text>`
+	candidates, except for the first element which follows the
+	`<line>.<column>[+<length>]@<timestamp>` format to define where the
+	completion apply in the buffer.
 *enum(value1|value2|...)*::
 	an enum, taking one of the given values
 *flags(value1|value2|...)*::
@@ -116,13 +122,7 @@ Builtin options
 		provides completion based on local filesystem
 
 	*option=<opt-name>*:::
-		where *opt-name* is a 'str-list' option. The first element
-		of the list should follow the format:
-
-			<line>.<column>[+<length>]@<timestamp>
-
-		to define where the completion apply in the buffer, and the
-		other strings are the candidates
+		where *opt-name* is a 'completions' option.
 
 *static_words* 'str-list'::
 	list of words that are always added to completion candidates