improve documentation for OTP connection

doc/source/user/advancedoptions.rst

@@ -38,11 +38,25 @@ procedure should not expose any sensitive information, you should consider if it
 against the security policies of the computing center you are working with.
 
 In order to deal with this kind of configuration, first set up the worker that
-requires an OTP in the standard way, as shown in the : ref:`projectconf worker` section.
+requires an OTP in the standard way, as shown in the :ref:`projectconf worker` section.
 Then, set the option ``interactive_login: true`` in the worker configuration.
 This will signal to the system that interaction from the user is required during the
 opening of the connection.
 
+In addition to the ``interactive_login`` option, there are two different use cases
+that should be handled separately by the user in the configuration:
+
+#. The connection requires **ssh key+OTP**: the ssh key **should be defined explicitly**
+   either in the ``~/.ssh/config`` file that defines the connection to the host, or
+   in the configuration of the worker (using the ``key_filename`` option).
+#. The connection requires **password+OTP**: no ssh key should be present in the
+   configuration files.
+
+.. warning::
+
+    The rest of the procedure is independent of which option is being used, but it
+    is crucial to properly define the options for the ssh key, depending on the use case.
+
 When starting the runner, the daemon should also be told that the user needs to
 input some information during the connection. The runner should thus be started with::
 

doc/source/user/introduction.rst

@@ -64,10 +64,11 @@ Once the daemon is started, the runner loops over the different actions that it
 perform and updates the state of Jobs in the database performing some actions on them.
 
 * After a Job has been ``CHECKED_OUT``, the Runner will proceed to upload the information required to run a Job. This includes:
-      - resolving all the references of the Job from the database (including everything in additional stores)
-      - using those data to generate a JSON representation of the Job without external references
-      - uploading a JSON file with this information on the runner
-  Once this is done, the state of the Job is ``UPLOADED``
+
+  - resolving all the references of the Job from the database (including everything in additional stores)
+  - using those data to generate a JSON representation of the Job without external references
+  - uploading a JSON file with this information on the runner
+  Once this is done, the state of the Job is ``UPLOADED``.
 * The runner generates a submission script suitable for the type of chosen worker.
   Uploads it and submits the job. The Job is now ``SUBMITTED``.
 * When the SLURM job starts running, the code on the worker deserializes the Job object and