diff --git a/README.asciidoc b/README.asciidoc
index 2b0612758..125ddc378 100644
--- a/README.asciidoc
+++ b/README.asciidoc
@@ -790,37 +790,21 @@ Custom key shortcuts can be registered through mappings.
 
 See <<doc/pages/mapping#,`:doc mapping`>>.
 
-Defining Commands
+Defining Commands and Aliases
 ~~~~~~~~~~~~~~~~~
 
 New commands can be created using `:define-command`.
 
 See <<doc/pages/commands#declaring-new-commands,`:doc commands declaring-new-commands`>>.
 
+They can be given additional short names depending of the scope with `:alias`.
+
+See <<doc/pages/commands#aliases,`:doc commands aliases`>>.
+
 Some helper commands are available to define composite commands.
 
 See <<doc/pages/commands#helpers,`:doc commands helpers`>>.
 
-Aliases
-~~~~~~~
-
-With `:alias` commands can be given additional names. Aliases are scoped, so
-that an alias can refer to one command for a buffer, and to another for another
-buffer. The following command defines `<alias>` as an alias for `<command>`:
-
---------------------------------
-:alias <scope> <alias> <command>
---------------------------------
-
-`<scope>` can be one of `global`, `buffer` or `window`.
-
--------------------------------------
-:unalias <scope> <alias> [<expected>]
--------------------------------------
-
-Will remove the given alias in the given scope. If `<expected>` is specified
-the alias will only be removed if its current value is `<expected>`.
-
 FIFO Buffers
 ~~~~~~~~~~~
 
diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc
index 125371a44..cc1b06af1 100644
--- a/doc/pages/commands.asciidoc
+++ b/doc/pages/commands.asciidoc
@@ -150,12 +150,12 @@ of the file onto the filesystem
 
 *alias* <scope> <name> <command>::
     define a new alias named *name* in *scope*
-    (See <<scopes#,`:doc scopes`>>)
+    (See <<aliases,Using aliases>> and <<scopes#,`:doc scopes`>>)
 
 *unalias* <scope> <name> [<command>]::
     remove an alias if its current value is the same as the one passed
     as an optional parameter, remove it unconditionally otherwise
-    (See <<scopes#,`:doc scopes`>>)
+    (See <<aliases,Using aliases>> and <<scopes#,`:doc scopes`>>)
 
 *evaluate-commands* [<switches>] <command> ...::
     *alias* eval +
@@ -404,3 +404,30 @@ Kakoune's state:
 --------------------------------------------------------
 def " print_selection %{ echo %sh{ ${kak_selection} } }"
 --------------------------------------------------------
+
+== Aliases
+
+With `:alias`, commands can be given additional names.
+As aliases are intended to be used interactively most of the time,
+they are often short. For example `:reg` is an alias for `:set-register`.
+
+They are scoped, so that an alias can refer to one command for a buffer,
+and to another for another buffer. For instance `:next` could be an alias
+for `grep-next-match` in a `*grep*` buffer while pointing to
+`:make-next-error` in a `*make*` buffer.
+
+The following command defines `<alias>` as an alias for `<command>`:
+
+--------------------------------
+:alias <scope> <alias> <command>
+--------------------------------
+
+`<scope>` can be one of `global`, `buffer` or `window`.
+
+-------------------------------------
+:unalias <scope> <alias> [<expected>]
+-------------------------------------
+
+Will remove the given alias in the given scope. If `<expected>` is specified
+the alias will only be removed if its current value is `<expected>`.
+