diff --git a/calamares/modules/shellprocess.conf b/calamares/modules/shellprocess.conf
index 4734aaa..07947f3 100644
--- a/calamares/modules/shellprocess.conf
+++ b/calamares/modules/shellprocess.conf
@@ -1,3 +1,6 @@
+# SPDX-FileCopyrightText: no
+# SPDX-License-Identifier: CC0-1.0
+#
 # Configuration for the shell process job.
 #
 # Executes a list of commands found under the key *script*.
@@ -12,7 +15,16 @@
 #
 # The (global) timeout for the command list can be set with
 # the *timeout* key. The value is a time in seconds, default
-# is 10 seconds if not set.
+# is 30 seconds if not set. The timeout **must** be tuned, either
+# globally or per-command (see below in the description of *script*),
+# to the load or expected running-time of the command.
+#
+#  - Setting a timeout of 30 for a `touch` command is probably exessive
+#  - Setting a timeout of 1 for a `touch` command might be low,
+#    on a slow disk where touch needs to be loaded from CDROM
+#  - Setting a timeout of 30 for a 1GB download is definitely low
+#  - Setting a timeout of 3600 for a 1GB download is going to leave
+#    the user in uncertainty for a loooong time.
 #
 # If a command starts with "-" (a single minus sign), then the
 # return value of the command following the - is ignored; otherwise,
@@ -21,16 +33,58 @@
 #
 # The value of *script* may be:
 #   - a single string; this is one command that is executed.
-#   - a list of strings; these are executed one at a time, by
+#   - a single object (this is not useful).
+#   - a list of items; these are executed one at a time, by
 #     separate shells (/bin/sh -c is invoked for each command).
-#   - an object, specifying a key *command* and (optionally)
-#     a key *timeout* to set the timeout for this specific
-#     command differently from the global setting.
+#     Each list item may be:
+#     - a single string; this is one command that is executed.
+#     - a single object, specifying a key *command* and (optionally)
+#       a key *timeout* to set the timeout for this specific
+#       command differently from the global setting.
+#
+# Using a single object is not useful because the same effect can
+# be obtained with a single string and a global timeout, but when
+# there are multiple commands to execute, one of them might have
+# a different timeout than the others.
+#
+# To change the description of the job, set the *name* entries in *i18n*.
 ---
+# Set to true to run in host, rather than target system
 dontChroot: false
-timeout: 10
+# Tune this for the commands you're actually running
+# timeout: 10
+
+# Script may be a single string (because false returns an error exit
+# code, this will trigger a failure in the installation):
+#
+# script: "/usr/bin/false"
+
+# Script may be a list of strings (because false returns an error exit
+# code, **but** the command starts with a "-", the error exit is
+# ignored and installation continues):
+#
+# script:
+#     - "-/usr/bin/false"
+#     - "/bin/ls"
+#     - "/usr/bin/true"
+
+# Script may be a list of items (if the touch command fails, it is
+# ignored; the slowloris command has a different timeout from the
+# other commands in the list):
 script:
     - "-touch @@ROOT@@/tmp/thingy"
-    - "/usr/bin/false"
+    - "/usr/bin/true"
     - command: "/usr/local/bin/slowloris"
       timeout: 3600
+
+# You can change the description of the job (as it is displayed in the
+# progress bar during installation) by defining an *i18n* key, which
+# has a *name* field and optionally, translations as *name[lang]*.
+#
+# Without a translation here, the default name from the source code
+# is used, "Shell Processes Job".
+#
+# i18n:
+#     name: "Shell process"
+#     name[nl]: "Schelpenpad"
+#     name[en_GB]: "Just a moment"