diff --git a/docs/launch.rst b/docs/launch.rst
index a00ceb9eb..ec254115c 100644
--- a/docs/launch.rst
+++ b/docs/launch.rst
@@ -4,6 +4,38 @@ Launching programs in new windows/tabs
 .. program:: launch
 
 
+|kitty| has a :code:`launch` action that can be used to run arbitrary programs
+in news windows/tabs. It can be mapped to user defined shortcuts in kitty.conf.
+It is very powerful and allows sending the contents of
+the current window to the launched program, as well as many other options.
+
+In the simplest form, you can use it to open a new kitty window running the
+shell, as shown below::
+
+    map f1 launch
+
+To run a different program simply pass the command line as arguments to
+launch::
+
+    map f1 launch vim path/to/some/file
+
+
+To open a new window with the same working directory as the currently
+active window::
+
+    map f1 launch --cwd=current
+
+To open the new window in a new tab::
+
+    map f1 launch --type=tab
+
+To pass the contents of the current screen and scrollback to the started process::
+
+    map f1 launch --stdin-source=@screen_scrollback less
+
+There are many more powerful options, refer to the complete list below.
+
+
 Syntax reference
 ------------------
 
diff --git a/docs/remote-control.rst b/docs/remote-control.rst
index 83df27dd2..212df731b 100644
--- a/docs/remote-control.rst
+++ b/docs/remote-control.rst
@@ -126,7 +126,7 @@ If you do not want to allow all programs running in |kitty| to control it, you c
 enable remote control for only some |kitty| windows. Simply create a shortcut
 such as::
 
-    map ctrl+k new_window @ some_program
+    map ctrl+k launch --allow-remote-control some_program
 
 Then programs running in windows created with that shortcut can use ``kitty @``
 to control kitty. Note that any program with the right level of permissions can
diff --git a/kitty/config_data.py b/kitty/config_data.py
index 20466d516..107c8fd84 100644
--- a/kitty/config_data.py
+++ b/kitty/config_data.py
@@ -1089,26 +1089,27 @@ g('shortcuts.window')  # {{{
 k('new_window', 'kitty_mod+enter', 'new_window', _(''), long_text=_('''
 You can open a new window running an arbitrary program, for example::
 
-    map kitty_mod+y      new_window mutt
+    map kitty_mod+y      launch mutt
 
 You can open a new window with the current working directory set to the
 working directory of the current window using::
 
-    map ctrl+alt+enter    new_window_with_cwd
+    map ctrl+alt+enter    launch --cwd=current
 
 You can open a new window that is allowed to control kitty via
 the kitty remote control facility by prefixing the command line with @.
 Any programs running in that window will be allowed to control kitty.
 For example::
 
-    map ctrl+enter new_window @ some_program
+    map ctrl+enter launch --allow-remote-control some_program
 
 You can open a new window next to the currently active window or as the first window,
 with::
 
-    map ctrl+n new_window !neighbor some_program
-    map ctrl+f new_window !first some_program
+    map ctrl+n launch --location=neighbor some_program
+    map ctrl+f launch --location=first some_program
 
+For more details, see :doc:`launch`.
 '''))
 if is_macos:
     k('new_window', 'cmd+enter', 'new_window', _('New window'), add_to_docs=False)