diff --git a/docs/glossary.rst b/docs/glossary.rst
index 118117ac1..93dc71a3b 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -55,8 +55,8 @@ Variables that influence kitty behavior
 
 .. envvar:: VISUAL
 
-   Controls what program kitty uses as an editor, when, for instance, opening
-   kitty.conf in response to :sc:`edit_config_file`
+   The terminal editor (such as ``vi`` or ``nano``) kitty uses, when, for
+   instance, opening :file:`kitty.conf` in response to :sc:`edit_config_file`.
 
 
 .. envvar:: EDITOR
diff --git a/docs/kittens/remote_file.rst b/docs/kittens/remote_file.rst
index 3c661a3a6..d7d3e4b30 100644
--- a/docs/kittens/remote_file.rst
+++ b/docs/kittens/remote_file.rst
@@ -17,9 +17,10 @@ Then hold down :kbd:`ctrl+shift` and click the name of the file.
 
 |kitty| will ask you what you want to do with the remote file. You can choose
 to *Edit* it in which case kitty will download it and open it locally in your
-``EDITOR``. As you make changes to the file, they are automatically transferred
-to the remote computer. Note that this happens without needing to install *any*
-special software on the server, beyond ``ls`` that supports hyperlinks.
+:envvar:`EDITOR`. As you make changes to the file, they are automatically
+transferred to the remote computer. Note that this happens without needing
+to install *any* special software on the server, beyond ``ls`` that supports
+hyperlinks.
 
 .. versionadded:: 0.19.0
 
diff --git a/kitty/options/definition.py b/kitty/options/definition.py
index 953a0fb1c..7f22a89be 100644
--- a/kitty/options/definition.py
+++ b/kitty/options/definition.py
@@ -2417,14 +2417,15 @@ starts in interactive mode and reads its startup rc files.
 
 opt('editor', '.',
     long_text='''
-The console editor to use when editing the kitty config file or similar tasks.
-The default value of ``.`` means to use the environment variables :envvar:`VISUAL`
-and :envvar:`EDITOR` in that order. Note that these environment variables have
-to be set when kitty starts, so if they're only set in shell startup scripts, but
-kitty is launched directly from your desktop, kitty will not see them. kitty does try
-to read the values from the shell as well, but this process is not entirely robust since
-there are a myriad different shells out there. In that case you're better off naming
-your favorite editor here.
+The terminal editor (such as ``vim`` or ``nano``) to use when editing the kitty
+config file or similar tasks.
+
+The default value of . means to use the environment variables :envvar:`VISUAL`
+and :envvar:`EDITOR` in that order. If these variables aren't set, kitty will
+run your shell (``$SHELL -l -c env``) to see if your shell config files set
+:envvar:`VISUAL` or :envvar:`EDITOR`. If that doesn't work, kitty will cycle
+through various known editors (``vim``, ``emacs``, etc) and take the first one
+that exists on your system.
 '''
     )