diff --git a/mpsd-software-environment.py b/mpsd-software-environment.py
index 12967c6379d74018685cfcfee5520b262bc5898d..76c297bc5293a82f51c77051c26bb01add8c2d34 100755
--- a/mpsd-software-environment.py
+++ b/mpsd-software-environment.py
@@ -46,7 +46,7 @@ def set_up_logging(loglevel="warning", filename=None):
 
     This function sets up the logging configuration for the script.
     It configures the log level, log format, and log handlers
-    for both file and console output.
+    for both file and console(=shell) output.
 
 
     Parameters
@@ -61,6 +61,14 @@ def set_up_logging(loglevel="warning", filename=None):
 
     If loglevel is 'debug', save line numbers in log messages.
 
+    Returns
+    -------
+
+    None.
+
+    Logger instances are generally not passed around, but retrieved from the
+    logging module as shown below (they are singletons).
+
     We provide two loggers:
 
     1. log = logging.getLogger('')
@@ -144,7 +152,7 @@ def set_up_logging(loglevel="warning", filename=None):
     # create formatter 'empty' formatter
     formatter = logging.Formatter("%(message)s")
 
-    # create, format and add console handler
+    # create, format and add handler for shell output
     ch = logging.StreamHandler()
     ch.setFormatter(formatter)
     print_log.addHandler(ch)