[docs] Review of Qt Application Manager documentation

* Simplified the documentation to improve readability
* Make sure the terminology is consistent across the component as well as Qt Automotive Suite

Task-number: AUTOSUITE-778
Change-Id: I068ce1917741e4278c2fff985f6e61c106e6a8e2
Reviewed-by: Robert Griebl <robert.griebl@pelagicore.com>

3 files changed, 280 insertions, 255 deletions

diff --git a/doc/configuration.qdoc b/doc/configuration.qdoc
index 1f74fc41..0adca9e7 100644
--- a/doc/configuration.qdoc
+++ b/doc/configuration.qdoc
@@ -33,7 +33,7 @@
 
 \section1 Main Configuration
 
-The application-manager can be configured through config files and the command line.
+The application manager can be configured through config files and the command line.
 The currently supported command-line options can always be displayed by running \c{appman --help}.
 Some of these options can also be set via config files, which in itself are referenced on the
 command-line with the \c{--config-file <filename>} option.
@@ -64,12 +64,12 @@ all your imports paths and file references relative to your main config file.
     \li \b --version
     \br \e -
     \li bool
-    \li Prints the current version of the application-manager and exits.
+    \li Prints the current version of the application manager and exits.
 \row
     \li \b --build-config
     \br \e -
     \li bool
-    \li Prints the build configuration of the application-manager in YAML format and exits.
+    \li Prints the build configuration of the application manager in YAML format and exits.
 \row
     \li \b --config-file or \c -c
     \br \e -
@@ -85,7 +85,7 @@ all your imports paths and file references relative to your main config file.
         \li maps will be merged with earlier maps recursively on a key-by-key basis, according to
             rules 1 and 2.
         \endlist
-        The application-manager will save the result of parsing and evaluating all the
+        The application manager will save the result of parsing and evaluating all the
         configuration files into a cache. This cache is loaded on subsequent starts if the exact
         same set of config files is used unchanged.
 
@@ -100,7 +100,7 @@ all your imports paths and file references relative to your main config file.
     \li \b --clear-config-cache
     \br \e -
     \li bool
-    \li Although the application-manager should detect if the configuration file cache is out of
+    \li Although the application manager should detect if the configuration file cache is out of
         sync, you can force-clear the cache on startup with this option.
 \row
     \li \b --option or \c -o
@@ -115,7 +115,7 @@ all your imports paths and file references relative to your main config file.
     \li \b --database
     \br \e applications/database
     \li string
-    \li To decrease the start up time of the System-UI, its application database can be cached
+    \li To decrease the start up time of the System UI, its application database can be cached
         in a file so that in subsequent start ups it doesn't have to scan and parse the
         \c info.yaml files of installed applications all over again. This option specifies the
         filepath of such cache file. (default: empty/disabled)
@@ -152,7 +152,7 @@ all your imports paths and file references relative to your main config file.
         WindowManager on the specified D-Bus: can be either \c session, \c system, \c none (for no
         registration at all) or a full D-Bus bus specification string. (default: \c session on
         Linux, \c none on all other platforms)
-        \note On production systems, you most likely want to put the application-manager on the
+        \note On production systems, you most likely want to put the application manager on the
               \c system bus, where you can set detailed security policies using standard D-Bus
               mechanisms, while keeping the NotificationManager on the session bus. See the more
               advanced config-file option \c dbus below.
@@ -179,20 +179,20 @@ all your imports paths and file references relative to your main config file.
     \li \b --no-fullscreen
     \br \e -
     \li bool
-    \li Override full-screen setting in the System-UI's config file. Useful for development on the
+    \li Override full-screen setting in the System UI's config file. Useful for development on the
         desktop. (default: false)
 \row
     \li \b -
     \br \e ui/windowIcon
     \li string
-    \li If set, the given image file will be used as a window icon for all application-manager
+    \li If set, the given image file will be used as a window icon for all application manager
         windows. This setting is only useful for development and will only take effect on Windows,
         macOS and Linux/X11.
 \row
     \li \b -I
     \br \e ui/importPaths
     \li array<string>
-    \li Adds additional QML import paths to the System-UI.
+    \li Adds additional QML import paths to the System UI.
 \row
     \li \b -
     \br \e ui/style
@@ -202,30 +202,30 @@ all your imports paths and file references relative to your main config file.
     \li \b -
     \br \e plugins
     \li map<array<string>>
-    \li A string-to-string-list map that defines plugins that the application-manager should load.
+    \li A string-to-string-list map that defines plugins that the application manager should load.
         The value must be a list of plugin library file path names. A single plugin will also be
         accepted. Currently the only valid key is \c startup. The plugin itself must implement the
-        StartupInterface. The application-manager will call the function hooks during startup of
-        the System-UI.
+        StartupInterface. The application manager will call the function hooks during startup of
+        the System UI.
 \row
     \target system properties
     \li \b -
     \br \e systemProperties
     \li object
-    \li Exports user-defined properties (key/value pairs) to the System-UI and applications. This
+    \li Exports user-defined properties (key/value pairs) to the System UI and applications. This
         field can only have the following children, that control access to the actual properties:
         \c private, \c protected and \c public (other children will be ignored). Properties under
         one of the access tags can be freely chosen and can also be nested. The properties
-        are exposed as ApplicationManager::systemProperties to the System-UI and as
+        are exposed as ApplicationManager::systemProperties to the System UI and as
         ApplicationInterface::systemProperties to all QML applications:
         \list
-        \li The System-UI has access to public, protected and private properties.
+        \li The System UI has access to public, protected and private properties.
         \li Built-in applilcations have access to public and protected properties.
         \li Installed (third party) applications have access to public properties only.
         \endlist
         Private keys will overwrite identical protected and public ones and protected keys will
         overwrite identical public ones. The properties will just be converted to QVariantMaps, but
-        the application-manager will not interpret them in any way.
+        the application manager will not interpret them in any way.
         Non-QML applications can access this data via the environment variable
         \c $AM_RUNTIME_SYSTEM_PROPERTIES as a YAML snippet.
 \row
@@ -233,7 +233,7 @@ all your imports paths and file references relative to your main config file.
     \br \e -
     \li bool
     \li Enable verbose output. All logging categories and message types will be enabled with the
-        exception of some Qt internal debug messages (\c logging-rules will be ignored). Note that
+        exception of some Qt internal debug messages; \c logging-rules will be ignored. Note that
         logging rules provided via the QT_LOGGING_RULES environment variable will still prevail.
         For more control over the logging output, see \c logging-rules below.
 \row
@@ -245,13 +245,13 @@ all your imports paths and file references relative to your main config file.
     \li \b --load-dummydata
     \br \e ui/loadDummyData
     \li bool
-    \li Loads QML dummy-data into the System-UI (just like \c qmlscene and \c qml would).
+    \li Loads QML dummy data into the System UI, similar to \c qmlscene and \c qml.
 \row
     \target no-security
     \li \b --no-security
     \br \e flags/noSecurity
     \li bool
-    \li Disables all security related checks. Use this in a development setup only! (default: false)
+    \li Disables all security related checks. Use this in a development setup only; never in production. (default: false)
 \row
     \li \b --development-mode
     \br \e flags/developmentMode
@@ -276,8 +276,8 @@ all your imports paths and file references relative to your main config file.
     \li \b --single-app
     \br \e -
     \li string
-    \li Runs the application-manager with a single application only (ignoring the database).
-        In this mode, the application-manager can act as a \c qmlscene / \c qml replacement.
+    \li Runs the application manager with a single application only (ignoring the database).
+        In this mode, the application manager can act as a \c qmlscene / \c qml replacement.
         The argument is the path to \c info.yaml. Aliases (\c{info-*.yaml}) will also be
         loaded from the given path.
 \row
@@ -285,7 +285,7 @@ all your imports paths and file references relative to your main config file.
     \br \e logging/rules
     \li array<string>
     \li Adds standard Qt logging rules - see the QLoggingCategory documentation for the required
-        format. Application-manager specific logging categories are listed in
+        format. application manager specific logging categories are listed in
         \l {Logging and Debugging}.
 \row
     \li \b -
@@ -336,7 +336,7 @@ all your imports paths and file references relative to your main config file.
     \li \b -
     \br \e quicklaunch/idleLoad
     \li real
-    \li This is a system-load value between \c 0 and \c 1. The application-manager will not start
+    \li This is a system-load value between \c 0 and \c 1. The application manager will not start
         a new quick-launcher, as long as the idle-load of the system is higher than this value.
         (default: 0)
 \row
@@ -375,7 +375,7 @@ all your imports paths and file references relative to your main config file.
     \li \b -
     \br \e crashAction
     \li object
-    \li Specifies which actions to take, if the application-manager is crashing. See
+    \li Specifies which actions to take, if the application manager is crashing. See
         \l{Crash Action Specification} {below} for more information.
 \row
     \li \b -
@@ -395,7 +395,7 @@ all your imports paths and file references relative to your main config file.
     \br \e ui/iconThemeSearchPaths
         \target iconThemeSearchPaths
     \li list<string>
-    \li Adds additional icon theme search paths to the System-UI and all apps. This can be used
+    \li Adds additional icon theme search paths to the System UI and all apps. This can be used
         to add a custom icon theme to the search path and load it by specifying
         \l{iconThemeName} {ui/iconThemeName}.
 
@@ -408,7 +408,7 @@ applicationUserIdSeparation: this should be factored out into a container plugin
 
 \section1 D-Bus Specification
 
-These YAML objects describe both which D-Bus interfaces are registered on as well as access
+These YAML objects describe both, which D-Bus interfaces are registered on, as well as access
 policies.
 
 \table
@@ -419,20 +419,19 @@ policies.
 \row
     \li \c register
     \li string
-    \li Register the interface on the specified D-Bus: can be either \c session, \c system, \c none
-        or \c ~ (for no registration at all) or a full D-Bus bus specification string.
+    \li Registers the interface on the specified D-Bus: can be either \c session, \c system, \c none,
+        \c ~ (for no registration at all), or a full D-Bus bus specification string.
 \row
     \li \c policy
     \li map<object>
     \li These optional access policies can be used either instead of or in addition to the standard
-        D-Bus policy configuration. The keys into this map are the (undecorated) D-Bus function
-        names (e.g. \c startApplication). As soon as a key is specified, the corresponding function's
-        access policy is \c deny, until you add \c allow criterias (all of them are and-ed):
-
-
+        D-Bus policy configuration. The keys into this map are the undecorated D-Bus function
+        names, such as \c startApplication. When a key is specified, the corresponding function's
+        access policy is \c deny, until you add \c allow criterias -- all of which are AND-ed
+        together.
 \endtable
 
-A simple example, that would only allow applications with the capability \c appstore, running with
+A simple example, that only allows applications with the capability \c appstore, running with
 user-id \c 1000 to call the installer's \c startPackageInstallation function, while preventing anyone
 to remotely call \c acknowledgePackageInstallation:
 
@@ -475,13 +474,14 @@ ApplicationInstaller::getInstallationLocation
 \row
     \li \c isDefault
     \li bool
-    \li Exactly one installation location can be the default location which must be mounted and
-        accessible at all times. This can be used by an UI application to get a sensible
-        default for the installation location that it needs to pass to \l{ApplicationInstaller::startPackageInstallation()}{startPackageInstallation()}.
+    \li Only one installation location can be the default location, which must be mounted and
+        accessible at all times. This location can be used by a UI application to get a sensible
+        default for the installation location that it needs to pass to
+        \l{ApplicationInstaller::startPackageInstallation()}{startPackageInstallation()}.
 \row
     \li \c installationPath
     \li string
-    \li The absolute file-system path to the base directory under which applications are installed.
+    \li The absolute file system path to the base directory under which applications are installed.
 \row
     \li \c documentPath
     \li string
@@ -551,13 +551,13 @@ an additional column specifying which runtime a configuration option applies to:
     \li \c backgroundColor
     \li qml
     \li string
-    \li If set, the main window of the app will get this color set as the default clear color. This
-        will also give the surface an 8-bit alpha buffer.
+    \li If set, the main window of the app gets this color set as the default clear color. This option
+        also gives the surface an 8-bit alpha buffer.
 \row
     \li \c quitTime
     \li qml
     \li int
-    \li Defines the grace period in milliseconds an application is given for shutting down. This is
+    \li Defines the grace period in milliseconds, that an application is given for shutting down. This is
         the time limit between receiving the \l{ApplicationInterface::quit()}{quit()} signal and responding with
         \l{ApplicationInterface::acknowledgeQuit()}{acknowledgeQuit()}. (default: 250).
 \row
@@ -565,20 +565,20 @@ an additional column specifying which runtime a configuration option applies to:
     \li qml
     \li object
     \li Specifies which actions to take, if a QML client application is crashing. See
-        \l{Crash Action Specification} {below} for more information.
+        \l{Crash Action Specification} for more information.
 \endtable
 
 \section1 Crash Action Specification
 
-These sub-objects specify which actions to take, if the application-manager or QML runtimes are
+These sub-objects specify which actions to take, if the application manager or QML runtimes are
 crashing.
 
 \note All of these actions only work on Linux.
 
-The following conditions will be handled:
+The following conditions are handled:
 
 \list
-\li Uncaught exceptions. Exceptions derived from \c std::exception will also show the \c {what()}
+\li Uncaught exceptions. Exceptions derived from \c std::exception also show the \c {what()}
     information.
 \li \c SIGSEGV
 \li \c SIGABRT
@@ -596,17 +596,17 @@ The following conditions will be handled:
 \row
     \li \c printBacktrace
     \li bool
-    \li Try to print a readable backtrace. Will use the primitive backtrace functionality from glibc,
-        unless libbacktrace was enabled at configure time (default: true).
+    \li Tries to print a readable backtrace. This type uses the primitive backtrace functionality
+        from glibc, unless \c libbacktrace was enabled at configure time (default: true).
 \row
     \li \c printQmlStack
     \li bool
-    \li Try to print a readable QML stack trace. This is similar to \c printBacktrace above, but
+    \li Tries to print a readable QML stack trace. This is similar to \c printBacktrace above, but
         prints the current QML function stack when the crash occurred (default: true).
 \row
     \li \c dumpCore
     \li bool
-    \li Will end the process via \c abort instead of \c _exit. This will dump a \c core file,
+    \li Ends the process via \c abort instead of \c _exit. This will dump a \c core file,
         depending on your kernel configuration (default: true).
 \row
     \li \c waitForGdbAttach
@@ -630,15 +630,15 @@ profile.
     \li \c desktopProfile
     \li string
     \li When running on a desktop, you can request a non-default OpenGL profile by setting this
-        value to either \c core or \c compatibility. Not specifying anything here will lead to Qt
-        using the default settings for this platform. OpenGL ES has no support for profiles, so this
+        value to either \c core or \c compatibility. If you do not specify anything here, Qt uses
+        the default settings for this platform. OpenGL ES has no support for profiles, so this
         setting is ignored on platforms using OpenGL ES.
-        \note Be aware that this is just a request. The application-manager will output a warning,
+        \note Be aware that this is just a request. The application manager will output a warning,
               if the requested profile does not match the actual profile.
 \row
     \li \c esMajorVersion
     \li int
-    \li When set, the application-manager will request the specified OpenGL ES major version. On
+    \li When set, the application manager will request the specified OpenGL ES major version. On
         the desktop, the given GLES version is transparently mapped to the corresponding desktop GL
         version.
         The current mapping table is as follows:
@@ -649,14 +649,15 @@ profile.
             \li 3.2 \unicode{0x2192} 4.6
         \endlist
 
-        \note Be aware that this is just a request. The application-manager will output a warning,
+        Make sure to either specify \e both \c esMajorVersion and \c esMinorVersion options; or
+        \e none at all.
+
+        \note Be aware that this is just a request. The application manager will output a warning,
               if the requested version does not match the actual version.
-        \note Also make sure to either specify \e both \c esMajorVersion and \c esMinorVersion
-              options or \e none at all.
 \row
     \li \c esMinorVersion
     \li int
-    \li When set, the application-manager will request the specified OpenGL ES minor version. See
+    \li When set, the application manager will request the specified OpenGL ES minor version. See
         \c esMajorVersion above for more information.
 \endtable
 
diff --git a/doc/installation.qdoc b/doc/installation.qdoc
index 9447334f..ff8b87f5 100644
--- a/doc/installation.qdoc
+++ b/doc/installation.qdoc
@@ -31,31 +31,29 @@
 \page installation.html
 \title Installation
 
-\section1 Platforms
+\section1 Supported Platforms
 
-The application-manager is tested regularly on these platforms:
+The application manager is tested regularly on these platforms:
 \list
 \li Windows (single-process)
 \li macOS (single-process)
 \li Linux desktop (single-process)
 \li Linux desktop (multi-process)
-    \note Due to the wildly varying stability of Wayland drivers, only the \b Intel and \b VMWare
-          drivers are supported. Other drivers may work, but may also need either special QtWayland
-          versions or specific firmware blobs for the GPU driver.
+    \note Due to the varying stability levels in Wayland drivers, only the \b Intel and \b VMWare
+          drivers are supported. While other drivers may work, they require either special
+          QtWayland versions or specific firmware blobs for the GPU driver.
 \endlist
 
-
 \section1 Prerequisites
 
-In order to build the application-manager with all its features, the following
-components are required:
+To build the application manager with all its features, the following components are required:
 
 \list
     \li \b Qt 5.9.0 or higher.
     \li \b libyaml 1.6 or higher.
     \li \b openssl 1.0.1 or higher \e{- Linux only}. At compile time, only the headers need to be
-           available. The needed libraries will be dynamically loaded at runtime.
-    \li \b libarchive 3.0 or higher \e{- only if you need the installer functionality}.
+           available. The necessary libraries are dynamically loaded at runtime.
+    \li \b libarchive 3.0 or higher \e{- if you need the installer functionality}.
 \endlist
 
 On Debian-based systems, this command installs the three required packages:
@@ -63,35 +61,36 @@ On Debian-based systems, this command installs the three required packages:
 apt-get install libyaml-dev libarchive-dev libssl-dev
 \endcode
 
-\note On platforms without \c pkg-config (for example, Windows and macOS) as well as on platforms lacking
-one of the dependencies, the bundled versions of these libraries from the \c 3rdparty folder will
-automatically be used instead. Make sure you are aware of the licensing implications, since these bundled
-3rdparty libs will be linked in as static libraries. This option is not meant for production, but for
-development and testing environments only.
+\note On platforms without \c pkg-config (for example, Windows or macOS) as well as on platforms
+that lack one of the dependencies, the bundled versions of these libraries from the \c 3rdparty
+folder are automatically used instead. Make sure you are aware of the licensing implications,
+since these bundled 3rdparty libs will be linked in as static libraries. This option is not meant
+for production, but for development and testing environments only.
+
+\section1 Multi-process vs. Single-process
 
-\section1 Multi- vs. Single-process
+By default, the application manager always tries to build in multi-process mode, but falls back
+to single-process mode, if certain dependencies are not available, such as:
 
-By default, the application-manager always tries to build in multi-process mode, but will fallback
-to single-process mode, if certain dependencies are not available:
 \list
 \li You are building for \b Linux.
-\li The \b QtWayland module is available.
-\li The \b QtDBus module is available.
+\li The \c QtWayland module is available.
+\li The \c QtDBus module is available.
 \endlist
 
-You can force the build mode though via the respective \c -config options \c force-multi-process and
-\c force-single-process (see below).
+You can force the build mode via the respective \c -config options \c force-multi-process and
+\c force-single-process, as described below.
+
 
+\section1 Build
 
-\section1 Building
+The application manager uses \c qmake for its build system. The basic installation steps are:
 
-The application-manager is using \c qmake for its build-system. This means that the basic
-installation steps are:
 \code
 qmake && make && make install
 \endcode
 
-There are various options that can be given to \c qmake to tailor the build to your needs:
+There are various options that can be given to \c qmake to tailor the build to suit your needs:
 
 \table
 \header
@@ -99,16 +98,16 @@ There are various options that can be given to \c qmake to tailor the build to y
   \li Description
 \row
   \li \c{-config force-libcrypto}
-  \li Force building against OpenSSL, even on Windows and macOS.
+  \li Force a build against OpenSSL, even on Windows and macOS.
 \row
   \li \c{-config force-system-libarchive}
-  \li Force building against the system libarchive.
+  \li Force a build against the system libarchive.
 \row
   \li \c{-config no-system-libarchive}
   \li Do not build against the system libarchive, even if one was detected.
 \row
   \li \c{-config force-system-libyaml}
-  \li Force building against the system libyaml.
+  \li Force a build against the system libyaml.
 \row
   \li \c{-config no-system-libyaml}
   \li Do not build against the system libyaml, even if one was detected.
@@ -117,64 +116,65 @@ There are various options that can be given to \c qmake to tailor the build to y
   \li Force a single-process build, even if Qt's Wayland \c compositor module is available.
 \row
   \li \c{-config force-multi-process}
-  \li Force a multi-process build - this will break if Qt's Wayland \c compositor module is not available.
+  \li Force a multi-process build - this will break if Qt's Wayland \c compositor module is not
+      available.
 \row
   \li \c{-config enable-tests}
-  \li Enable building of all unit-tests.
+  \li Enable a build of all unit-tests.
 \row
   \li \c{-config disable-installer}
     \target config disable installer
   \li Disable the installer part.
 \row
   \li \c{-config disable-external-dbus-interfaces}
-  \li Completely disable the external D-Bus interfaces. The internal communication channel between the
-      applications and the application-manager will still be based on a peer-to-peer D-Bus though.
+  \li Completely disable the external D-Bus interfaces. The internal communication channel between
+      the applications and the application manager will still be based on a peer-to-peer D-Bus.
 \row
   \li \c{-config tools-only}
   \li Build tools only: \l{Controller}{appman-controller} and \l{Packager}{appman-packager}.
 \row
   \li \c{-config install-prefix=<path>}
   \li Uses \c path as the base directory for \c{make install}.
-      If you are not specifying an \c install-prefix when running qmake, then the application-manager
+      If you do not specify an \c install-prefix when you run qmake, then the application manager
       will behave like a standard Qt module:
       \list
       \li in developer builds, the binaries will be compiled directly to \c ${qtbase}/bin
       \li in prefix builds, the binaries will be compiled to \c ${builddir}/bin
       \endlist
 
-      If you specify an \c install-prefix, this will change:
+      If you specify an \c install-prefix, this means:
       \list
       \li in developer builds, the binaries will be compiled directly to \c ${install-prefix}/bin
       \li in prefix builds, the binaries will be compiled to \c ${builddir}/bin
       \endlist
 
-      In addition, all binaries on Linux will get an absolute \c RPATH / \c RUNPATH when configured
-      with an \c install-prefix. This will allow you to run the binaries from the build directory
-      directly without weird side-effects (Linux will just pull in the system-Qt, if it cannot find
+      Additionally, all binaries on Linux will get an absolute \c RPATH / \c RUNPATH when configured
+      with an \c install-prefix. This allows you to run the binaries from the build directory
+      directly without any weird side-effects. Linux pulls in the system-Qt, if it cannot find
       the necessary libs in \c RUNPATH.
 
-      In any case, the application-manager is a Qt module. This means that all libraries and headers
+      Ultimately, the application manager is a Qt module. This means that all libraries and headers
       are always installed into \c ${qtbase} to make them accessible via standard Qt mechanisms.
-
 \row
   \li \c{-config systemd-workaround}
-  \li Paramount if you are running systemd and plan on supporting SD-Card installations. Works
+  \li Paramount if you are running systemd and plan to support SD-Card installations. Works
       around systemd interfering with loopback mounts.
 \row
   \li \c{-config enable-widgets}
-  \li Enables support for Qt widgets. Enabling this option can be useful to enable the use of some
+  \li Enables support for Qt widgets. This option can be useful to enable the use of some
       development graphical tools using Qt widgets.
 \row
   \li \c{-config hardware-id=<id>}
-  \li Compiles in \c id as a hard-coded hardware-id (see below for more information)
+  \li Compiles in \c id as a hard-coded hardware ID; see \l{The Hardware ID} for more information.
 \row
   \li \c{-config hardware-id-from-file=<file>}
-  \li The hardware-id will be read from the specified \c file at runtime (see below for more information)
+  \li The hardware-id is read from the specified \c file at runtime; see \l{The Hardware ID} for
+      more information.
 \row
   \li \c{-config enable-libbacktrace}
-  \li Enables building and linking against \c libbacktrace in the 3rdparty folder. This will give
-      you readable backtraces on crash, but will also increase the binary size slightly.
-      This is enabled by default for debug builds.
+  \li Enables building and linking against \c libbacktrace in the 3rdparty folder. This gives
+      you readable backtraces on crash, but also increases the binary size slightly. For debug
+      builds, this option is enabled by default.
 \row
   \li \c{-config disable-libbacktrace}
   \li Disables building and linking against \c libbacktrace in the 3rdparty folder.
@@ -182,85 +182,89 @@ There are various options that can be given to \c qmake to tailor the build to y
 
 \section2 The Hardware ID
 
-The installer part of the application-manager needs an unique device id for two purposes:
+The installer part of the application manager needs a unique device ID for two reasons:
 \list 1
 \li If you want to deliver application packages that are bound to a specific device unit from your
-    app-store. The use case is that you don't want customers buying apps and then sharing them
+    app-store. The use case here is to prevent customers from buying apps once and then sharing them
     with others for free.
 
-\li When installing application packages onto an SD card that can be removed by the user. The use
+\li When you install application packages onto an SD card that can be removed by the user. The use
     case here is that we need to be able to detect which SD card "belongs" to which device, in case
-    the user is swapping a card between devices.
+    the user is swapping the same card between devices.
 \endlist
 
-Since the application-manager doesn't know at build time how a potential app-store will be
-configured, and if installations on removable SD-cards are enabled, it tries to create an unique id
-based on the MAC address of the first configured ethernet device. If the ethernet device is not
-configured at all (or configured after the start of the application-manager), this will obviously
-not work.
+Since the application manager doesn't know, at build time, how a potential app-store will be
+configured, and if installations on removable SD-cards are enabled, the application manager tries
+to create a unique ID based on the MAC address of the first configured ethernet device. If the
+ethernet device is not configured at all, or configured after the application manager starts, this
+scenario will not work.
 
-All in all, there are 3 different methods to specify an id:
+There are three different ways to specify a hardware ID:
 
 \list 1
-\li No configure option: use the MAC of the first ethernet device. Works in 90% of all cases out of
-    the box.
-
-\li \c{qmake --config hardware-id=foo} hardcodes the id to \c foo. This is ideal, if you do not use
-    any application-manager features that require this id to be unique and if you cannot (or do not
-    want to) guarantee that an ethernet device is up when starting the application-manager.
-
-\li \c{qmake --config hardware-id-from-file=bar} makes the application-manager read the contents of
-    the file \c bar at startup and use its content as the id instead of the ethernet MAC. Useful if
-    your device has a unique device id available via \c /proc or \c /sys and you want to use
-    features requiring such an id.
+\li No configure option: use the MAC address of the first ethernet device. Typically, this option
+    works out of the box.
+
+\li \c{qmake --config hardware-id=yourID} hardcodes the ID to \c yourID. This option is ideal, if
+    you do not use any application manager features that require this ID to be unique and if you
+    cannot (or do not want to) guarantee that an ethernet device is up when the application manager
+    starts.
+
+\li \c{qmake --config hardware-id-from-file=yourFile} makes the application manager read the
+    contents of \c yourFile at startup and uses its content as the ID; instead of the ethernet MAC
+    address. This option is useful if your device has a unique device ID available via \c /proc or
+    \c /sys and you want to use features that require such an ID.
 \endlist
 
-All executables (including the unit-tests) can be found in the build folder's \c bin directory after
+All executables, including the unit tests, can be found in the build folder's \c bin directory, after
 compiling.
 
-\section1 Generating Code-Coverage Data
+\section1 Generate Code-Coverage Data
 
 Instead of doing a normal build, you can also create a coverage build by running \c{make coverage}.
-As every compile step needs to be instrumented with special compiler flags, you need to make sure
-to run \c{make clean} before.
-Using a build like this enables you to generate HTML coverage reports simply by executing:
+Since every compile step needs to be instrumented with special compiler flags, make sure to run
+\c{make clean} before \c{make coverage}.
+
+Using a build like this enables you to generate HTML coverage reports with the following command
+in the build directory:
 
 \badcode
 make check-coverage
 \endcode
 
-in the build directory. The command-line output will tell you the url to the generated report.
+The command line output provides you the URL to the generated report.
 
 \section1 System Setup
 
-The runtime configuration of the application-manager is done through command-line switches and
+The runtime configuration of the application manager is done through command line switches and
 one or more configuration files.
 
 Normally, the basic configuration is done via two separate config files:
 one for target system specific setup and one for System-UI specific settings. The
 default location for the system specific part is \c{/opt/am}. A standard
-setup is shipped with the application-manager in the \c{template-opt} directory.
-You can either stick with the default:
+setup is shipped with the application manager in the \c{template-opt} directory.
+
+You can stick with the default, via the following command:
 
 \badcode
 sudo cp -r template-opt/am /opt
 sudo chown $(whoami) /opt/am -R
 \endcode
 
-or you could copy the contents of \c{template-opt} somewhere else; be sure to
-edit the contained \c{config.yaml} file to reflect the changed paths.
+Alternatively, you can copy the contents of \c{template-opt} somewhere else; be sure to
+edit the \c{config.yaml} file to reflect the changed paths.
 
-Once this is done, add a file called \c{am-config.yaml} to your System-UI
-with UI specific settings (for example, QML import path, path to built-in apps).
+Once this is done, add a file called \c{am-config.yaml} to your System-UI with UI specific
+settings. For example, the QML import path, path to built-in apps, and so on.
+
+With everything in place, you can start the application manager:
 
-With everything in place, you can start the application-manager:
 \badcode
 cd /path/to/system-ui
 appman -c /opt/am/config.yaml -c am-config.yaml -r --verbose main.qml
 \endcode
 
-
-\c{-r} makes sure to recreate the apps database and \c{--verbose} will give you verbose output,
+\c{-r} makes sure to recreate the apps database and \c{--verbose} gives you verbose output,
 which is quite helpful when first setting up the environment.
 
 */
diff --git a/doc/singlevsmultiprocess.qdoc b/doc/singlevsmultiprocess.qdoc
index 871d23c6..43844b81 100644
--- a/doc/singlevsmultiprocess.qdoc
+++ b/doc/singlevsmultiprocess.qdoc
@@ -29,166 +29,186 @@
 /*!
 
 \page singlevsmultiprocess.html
-\title Single- vs. Multi-Process Mode
+\title Single-Process vs. Multi-Process Mode
 
-Single-process mode is only supported by QML applications: applications that use the \c qml or
-\c qml-inprocess runtime. Consequently the comparison between single- and multi-process mode only
-applies to this kind of applications. In multi-process mode the System-UI (compositor) and the
-applications each run in their own dedicated process. In single-process mode, as the name implies,
-there is only one process: the System-UI process and all applications run within this process.
+The application manager can run the System UI and QML applications in two different modes:
 
-For a better understanding of the two modes, here is how QML works internally: in every process
-(aka. address-space), you can only have one Qt platform (QPA) plugin. The QPA plugin decides how
-many top-level windows you can open. If you are using a low-level plugin that does not talk to a
-windowing system (e.g. EGL full-screen on an embedded device), you can only open one full-screen
-window - the System-UI. Now every top-level window can only have one scene-graph and every tree of
-QtQuick items needs to be tied to exactly one scene-graph. This means that you will always have
-exactly one window, one scene-graph and one QML engine in your System-UI, no matter whether
-applications run within the System-UI process or in separate processes.
+\list 1
+   \li Single-process mode: where the System UI and QML applications are all run in \b one, single
+       process, that belongs to the System UI. This mode is only supported by QML applications -
+       applications that use the \qml or \qml-inprocess runtime.
+   \li Multi-process mode: where the System UI and QML applications all run in their own, dedicated
+       process.
+\endlist
+
+Internally, for every Qt application, which is ultimately a process, you can have only one Qt
+Platform (QPA) Plugin. To interact with the underlying window system, Qt needs to load this plugin
+first. The QPA plugin decides how many top-level windows you can open; but Qt can only load one
+such plugin at any point and it cannot be switched out at runtime. If you are using a low-level
+plugin, one that does not talk to a windowing system, such as EGL full-screen on an embedded
+device, you can only open one full screen window: the System UI.
+
+Now, each top-level window can have only one scene graph, and each tree of QtQuick items needs to
+be ties to only one scene graph. Consequently, you will always have only one window, one scene
+graph, and one QML engine in your System UI; no matter whether applications run within the
+System UI's process, or in separate processes.
 
 
 \section1 Single-process Mode
 
-The single-process mode exists for a reason, and that is to allow:
+The single-process mode allows for:
+
 \list
-\li Specific system applications to run with maximum performance (no compositing)
-\li Scaling down your system to target hardware that has not enough RAM/GPU resources to run
-    multi-process
-\li Do development on platforms that do not (yet) support multi-process mode (read: Windows, macOS,
-    Android, QNX, any targets with broken Wayland drivers)
+   \li Specific system applications to run with maximum performance, with no compositing
+   \li Scaling down your system to target hardware that lacks RAM/GPU resources to run in
+       multi-process mode
+   \li Development on platforms that do not yet support multi-process mode, such as Windows, macOS,
+       Android, QNX, as well as targets with broken Wayland drivers
 \endlist
 
-All of the above of course comes at the cost of (a) stability and (b) testability (you cannot test
-your components isolated, which makes diagnosing errors or crashes very hard).
+However, the cost of using single-process mode is reduced stability and testability: you cannot
+test your components in isolation, which makes it difficult to diagnose errors or crashes.
+
+In operating systems, the concept of a process is intertwined with the concept of isolation.
+Processes cannot easily affect each other - the operating system ensures this to the best of its
+ability. This isolation is crucial, both from a security standpoint and for stability. If a process
+crashes, it won't take down another process along the way, for example.
 
-There is one caveat here: you have to be aware that whatever the application-manager may be able to
-do, in single-process mode you are still within a single address-space, so you will always be able
-to hack your way around any "barrier". The only definite, enforceable barrier is process isolation,
-also known as multi-process mode.
+Sometimes, this isolation can hinder you, as a developer, if you need to cross this boundary to
+communicate with another process. Then, you need to make an effort to do this correctly, by using
+dedicated inter-process communication mechanisms, typically available as APIs.
 
+If all your code runs within the same process, then you can avoid the use of tedious and
+asynchronous inter-process communication channels. Instead, you can directly access variables and
+call functions that you need.
 
-\section1 Build- and Runtime Options
+\section1 Configuration
 
-The application-manager is built with multi-process support, if Qt's Wayland compositor module is
-available - that is if no special option is provided to qmake: multi-process support can always be
-disabled explicitly by adding the option \c {-config force-single-process}. On the other hand if
-\c {-config force-multi-process} is provided and the compositor is not available, the configuration
-step will fail.
+Since single-process mode only has one QML engine, shared amongst the System UI and all
+applications, any QML import paths provided, for example via \c am-config.yaml, is taken into
+consideration when the engine is resolving import statements. Import statements provided by the
+application manifest file, \c info.yaml, are only considered once the application has started,
+but is still loaded even after the application has stopped.
 
-In case the application-manager supports only single-process, QML applications that use the \c qml
-runtime will always run in-process, i.e. in the same process as the System-UI. Native applications
-will be omitted in this case, since they can only run in a dedicated process (of course, native
-applications can also use QML code). The difference is basically the entry point: \c native
-runtimes have an executable and \c qml runtimes a main QML file. For the latter the
-application-manager provides the executable (\c appman-launcher) in multi-process mode.
+In multi-process mode, only import paths specific to an application are considered. Additionally,
+absolute import paths cannot be used in \c info.yaml files, due to potential restrictions imposed
+by containers and for security reasons.
 
-If the application-manager is built with multi-process support, it can still be forced to run in
-single-process-mode by passing \c --force-single-process on the command line. This will result in
-the same runtime behavior as described above. Even when running the application-manager in
-multi-process mode it does not necessarily mean that QML applications get a dedicated process: if
-they use the \c qml-inprocess runtime they will execute in-process within the System-UI.
+In general, paths defined in the configuration might be provided to QML as absolute paths in
+single-process mode; but as relative paths in multi-process mode.
 
+\note In single-process mode, some configuration options have no effect, such as: \c quicklaunch,
+      \c quicklaunchQml, \c crashAction, and so on.
 
-\section1 Configuration
 
-Since there is only one QML engine in single-process mode shared by the System-UI and all
-applications, any QML import paths provided (e.g. through am-config.yaml) will be considered when
-resolving import statements. Import statements provided by an application manifest file (info.yaml)
-will only be considered once the application has been started, but will outlive its "termination".
-In multi-process mode only import paths specific to an application are considered. Besides,
-absolute import paths cannot be used in info.yaml files in multi-process mode, because of potential
-restrictions imposed by containers and for security reasons.
+\section1 Build and Runtime Options
 
-In general paths defined in the configuration might be provided to QML as absolute paths in
-single-process mode, but relative in multi-process mode.
+The application manager is built with multi-process support, as long as Qt's Wayland compositor
+module is available. To disable multi-process support, explicitly specify the
+\c {-config force-single-process} option. If you specify the \c {-config force-multi-process}
+option, and the compositor is not available, the configuration step fails.
 
-Also note that some configuration options are meaningless in single-process mode, e.g.
-\c quicklaunch, \c quicklaunchQml, \c crashAction, etc.
+If the application manager supports single-process mode only, QML applications that use the \c qml
+runtime will always run in the same process as the System UI. In this case, native applications
+are omitted, since they can only run in a dedicated process. This difference is the entry point:
+\c native runtimes have an executable and \c qml runtimes have a main QML file. For the latter the
+application manager provides the executable (\c appman-launcher) in multi-process mode.
+
+If the application manager is built with multi-process mode, you can still force it to run in
+single-process mode by passing \c --force-single-process on the command line. This results in
+the same runtime behavior as described above. Even when running the application manager in
+multi-process mode it does not necessarily mean that QML applications get a dedicated process: if
+they use the \c qml-inprocess runtime they will execute in-process within the System UI.
 
 
-\section1 Lifetime
+\section1 Application Lifetime
 
-The most obvious difference is that a crashing application in single-process mode will terminate
-the entire program, whereas in multi-process mode the System-UI and other applications keep on
-running. In multi-process mode the System-UI even gets notified when an application crashed and
-can react on it, e.g. by restarting the application.
+A key point to note is that, when an application in single-process mode crashes, it terminates the
+entire program. In contrast, when an application in multi-process mode crashes, the System UI and
+other applications keep on running. In multi-process mode the System UI is even notified when an
+application crashes and can react on it, for example by restarting the application.
 
-The usage of QML singletons in an application has some implications. In the QML world, singletons
-live in their own private, but also absolutely global context - they are even shared between
-multiple QML engine instances. Singletons are instantiated on first usage once and for all, as long
-as the process exists. This means that if an application is "terminated" in single-process mode,
-any singleton that had already been instantiated will persist and keep its current state.
-Consequently, when the application is restarted again, the state might be different from the
-multi-process case, where the singleton is instantiated anew.
+The usage of QML singletons in an application has some implications. In QML, singletons live in
+their own private, but global context - they are even shared between multiple QML engine instances.
+Singletons are instantiated on once and for all, on first use, and remain as long as the process
+exists. This means that if an application is terminated in single-process mode, any singleton that
+was already instantiated will persist and keep its current state. Consequently, when the
+application is restarted again, the singleton's state may differ from the multi-process case, where
+the singleton is instantiated anew.
 
 
 \section1 Application Windows
 
-A major difference between single- and multi-process mode is how windows are represented. Windows
-are exposed from the application to the System-UI through WindowManager::windowReady. For
-convenience and to serve as a replacement for Qt's standard \c qmlscene and \c qml tools, it is
-possible to use plain QML Windows in applications or even an Item as the root element. However, if
-close resemblance between single- and multi-process mode is the goal, there is no way around using
-an ApplicationManagerWindow. There are other benefits when using an ApplicationManagerWindow, as
-well (e.g. window properties).
+Windows are represented differently, whether you run your application in single-process or
+multi-process mode. Windows are exposed from the application to the System UI through
+\l{WindowManager::windowAdded}. For convenience and to serve as a replacement for Qt's standard
+\c qmlscene and \c qml tools, it is possible to use plain QML Windows in applications or even an
+Item as the root element. However, if you require close resemblance between single-process and
+multi-process mode for your application, you have to use an \l{ApplicationManagerWindow}. There
+are also other benefits to using an ApplicationManagerWindow, such as window properties.
 
-In multi-process mode an ApplicationManagerWindow derives from Window and in single-process mode
-from QtObject. So several properties coming from Window won't have any effect in single-process
-mode, although ApplicationManagerWindow will still define them for compatbility purposes.
+In multi-process mode an ApplicationManagerWindow derives from Window; unlike in single-process
+mode which derives from QtObject. As a result, several properties coming from Window won't have any
+effect in single-process mode, although ApplicationManagerWindow still defines them for
+compatibility. The following are some examples:
 
 \list
-\li An ApplicationManagerWindow is exposed to the System-UI in two different ways: in multi-process
-    mode a handle to the window's content surface is sent over the process boundary via the Wayland
-    protocol. The System-UI gets this as a surface Item, which is hierarchically independent from
-    the application's window. In single-process mode the ApplicationManagerWindow provides its
-    contentElement Item directly to System-UI. Consequently, it's possible for an application to
-    gain access to Items from System UI itself or from any other running application as they are
-    all sharing the same QML scene.
-\li Many properties, functions and signals defined in a Window are not reimplemented (yet) in the
+\li An ApplicationManagerWindow is exposed to the System UI in two different ways.
+    \list
+       \li In multi-process mode, a handle to the window's content surface is sent over the process
+           boundary via the Wayland protocol. The System UI gets this as a surface Item, which is
+           hierarchically independent from the application's window.
+       \li In single-process mode, the ApplicationManagerWindow provides its \c contentElement Item
+           directly to System UI. Consequently, it's possible for an application to gain access to
+           Items from System UI itself or from any other running application as they are all
+           sharing the same QML scene.
+    \endlist
+\li Many properties, functions, and signals defined in a Window are not yet reimplemented in the
     single-process version of ApplicationManagerWindow.
 \li An error encountered in a code block due to properties or methods described above will cause
-    subsequent statements not to be evaluated in multi-process mode, whereas in single-process mode
-    they are.
+    subsequent statements not to be evaluated in multi-process mode; but this is not the case in
+    single-process mode.
 \endlist
 
 
 \section1 Resource Consumption
 
-CPU usage on a multi-core system might be more efficient in multi-process mode, since the OS can
+CPU usage on a multi-core system may be more efficient in multi-process mode, since the OS can
 schedule more processes and potentially better utilize the cores.
 
-The memory consumption per application in multi-process mode is higher compared to single-process
-mode. There is more memory needed by the GPU due to additional window surface buffers that need to
-be allocated and also textures that hold application assets are not shared. If two applications
-render the same image (file), two textures are created in multi-process mode, in single-process
-mode only one.
+However, the memory consumption per application in multi-process mode is higher compared to
+single-process mode. The GPU needs more memory, to allocate additional window surface buffers.
+Also, textures that hold application assets are not shared. If two applications render the same
+image file, two textures are created in multi-process mode; instead of one only one in
+single-process mode.
 
-The CPU memory consumption per application is higher due to additional data structures, for
-instance if one application is running there are two instances of the QML engine in multi-process
-mode: one for the System-UI and one for the application. In single-process mode there is only one
-instance since everything is running within the System-UI. Also assets might be duplicated in
+The CPU memory consumption per application is higher due to additional data structures. For
+instance, if one application is running, there are two instances of the QML engine in multi-process
+mode: one for the System UI and one for the application. In single-process mode there is only one
+instance since everything is running within the System UI. Also assets might be duplicated in
 multi-process mode. This can be mitigated though, by using shared image providers or by removing
-images from CPU memory once they are uploaded to GPU memory (through environment variable
-QSG_TRANSIENT_IMAGES).
+images from CPU memory once they are uploaded to GPU memory, via the QSG_TRANSIENT_IMAGES
+environment variable.
 
 On the other hand, multi-process mode comes with the big advantage, that applications which are not
-needed any more can be terminated and hence will free their allocated resources again. In
-single-process mode applications are never really terminated, so their memory is not freed and the
-total consumption grows steadily with each started application, no matter, whether they have been
-stopped again. The QML engine simply doesn't allow to unload parts of the object hierarchy.
+needed any more can be terminated and hence will free their allocated resources. In single-process
+mode applications are never really terminated, so their memory is not freed, causing the total
+consumption to grow steadily with each application starting, no matter, whether they have been
+stopped. The QML engine doesn't allow you to unload parts of the object hierarchy.
 
 
-\section1 Recommended Way to Support Mixed Setups
+\section1 Support for Single-Process and Multi-Procecss Mode in One Application
 
-Define a set of inter-process communication (IPC) interfaces between the application and System-UI
-and stick to them - make this a review policy. You could use any IPC mechanism you see fit, but to
-make your lives easier, the application manager comes with an IPC mechanism that already fully
-abstracts the single- vs. multi-process difference, plus it makes it easy to create new interfaces
-for QML developers.
+If your application needs to support both, single-process mode and multi-process mode, you must
+define a set of Inter-Process Communication (IPC) interfaces between the application and System UI,
+and always stick to them. Consider making these interfaces part of your review policy. While you
+can use any IPC mechanism that suits your use case, the application manager includes an IPC
+mechanism that fully abstracts the single-process vs. multi-process difference. This mechanism
+also makes it easy to create new interfaces for QML developers.
 
-Please be aware that the application-manager IPC is not suitable to interface your complete
-middle-ware! Its sole purpose is to avoid a whole zoo of little one-off daemons that would be
-needed to keep track of different pieces of state information that need to be shared between the
-System-UI and all (or best case, only specific) applications.
+Be aware that the application manager's IPC is not suitable to interface your entire middleware.
+Its sole purpose is to avoid a situation where there is a large number of one-off daemons that need
+to be kept track of, involving various pieces of state information that need to be shared between
+the System UI and some or all applications.
 
 */