diff --git a/README.asciidoc b/README.asciidoc
index 53c9d917..2f14e382 100644
--- a/README.asciidoc
+++ b/README.asciidoc
@@ -272,6 +272,17 @@ selection.
 Registers are lists, instead of simply text in order to interact well with
 multiselection. Each selection have it's own captures, or yank buffer.
 
+Macros
+------
+
+Kakoune can record and replay a sequence of key press.
+
+When pressing the _Q_ key, followed by an alphabetic key for the macro name, 
+Kakoune begins macro recording: every pressed keys will be added to the
+macro until the _Q_ key is pressed again.
+
+To replay a macro, use the _q_ key, followed by the macro name.
+
 Search selection
 ----------------
 
diff --git a/src/normal.cc b/src/normal.cc
index 57b50dc9..7c603ee8 100644
--- a/src/normal.cc
+++ b/src/normal.cc
@@ -1040,8 +1040,8 @@ KeyMap keymap =
     { alt('r'), rotate_selections },
     { alt('R'), rotate_selections_content },
 
-    { 'q', start_or_end_macro_recording },
-    { 'Q', replay_macro },
+    { 'q', replay_macro },
+    { 'Q', start_or_end_macro_recording },
 
     { '`', for_each_char<to_lower> },
     { '~', for_each_char<to_upper> },