diff --git a/docs/kittens/ssh.rst b/docs/kittens/ssh.rst
index 34f6952f4..1583ed2d9 100644
--- a/docs/kittens/ssh.rst
+++ b/docs/kittens/ssh.rst
@@ -54,6 +54,33 @@ quick example:
 See below for full details on the syntax and options of :file:`ssh.conf`.
 
 
+A real world example
+----------------------
+
+Suppose you often SSH into a production server, and you would like to setup
+your shell and editor there using your custom settings. However, other people
+could SSH in as well and you don't want to clobber their settings. Here is how
+this could be achieved using the ssh kitten with zsh and vim as the shell and
+editor, respectively:
+
+.. code-block:: conf
+
+   # Have these settings apply to servers in my organization
+   hostname *.my-organization.net
+
+   # Setup zsh to read its files from my-conf/zsh
+   env ZDOTDIR $HOME/my-conf/zsh
+   copy --dest my-conf/zsh/.zshrc .zshrc
+   copy --dest my-conf/zsh/.zshenv .zshenv
+   # If you use other zsh init files add them in a similar manner
+
+   # Setup vim to read its config from my-conf/vim
+   env VIMINIT $HOME/my-conf/vim/vimrc
+   env VIMRUNTIME $HOME/my-conf/vim
+   copy --dest my-conf/vim .vim
+   copy --dest my-conf/vim/vimrc .vimrc
+
+
 .. include:: /generated/conf-kitten-ssh.rst
 
 
diff --git a/docs/shell-integration.rst b/docs/shell-integration.rst
index 5c11b2451..95f035a3a 100644
--- a/docs/shell-integration.rst
+++ b/docs/shell-integration.rst
@@ -194,13 +194,27 @@ code used for each shell below:
    </details>
 
 
+Shell integration over SSH
+----------------------------
+
+The easiest way to have shell integration work when SSHing into remote systems
+is to use the :doc:`ssh kitten <kittens/ssh>`. Simply run::
+
+    kitty +kitten ssh hostname
+
+And, by magic, you will be logged into the remote system with fully functional
+shell integration. Alternately, you can :ref:`setup shell integration manually
+<manual_shell_integration>`, by copying the kitty shell integration scripts to
+the remote server and editing the shell rc files there, as described below.
+
+
 .. _manual_shell_integration:
 
 Manual shell integration
 ----------------------------
 
 The automatic shell integration is designed to be minimally intrusive, as such
-it wont work for sub-shells, terminal multiplexers, containers, remote systems, etc.
+it wont work for sub-shells, terminal multiplexers, containers, etc.
 For such systems, you should setup manual shell integration by adding some code
 to your shells startup files to load the shell integration script.
 
@@ -248,11 +262,9 @@ The value of :envvar:`KITTY_SHELL_INTEGRATION` is the same as that for
 completely, in which case simply do not set the
 :envvar:`KITTY_SHELL_INTEGRATION` variable at all.
 
-If you want this to work while SSHing into a remote system, then you will
-need to add some code to the snippets above to check if :envvar:`KITTY_INSTALLATION_DIR`
-is empty and if so to set it to some hard coded location with the shell
-integration scripts that need to be copied onto the remote system.
-
+In a container, you will need to install the kitty shell integration scripts
+and make sure the :envvar:`KITTY_INSTALLATION_DIR` environment variable is set
+to point to the location of the scripts.
 
 Integration with other shells
 -------------------------------