documentation improvements

7 files changed, 80 insertions, 37 deletions

diff --git a/doc/administration/backup.rst b/doc/administration/backup.rst
index fb379bc..0643728 100644
--- a/doc/administration/backup.rst
+++ b/doc/administration/backup.rst
@@ -15,13 +15,19 @@ case data is lost due unforseen reasons.
 Backup
 ------
 
-The Fietsboek data lives in two places: Most of it is saved in the database,
-while track images and other "big files" are saved in the data directory.
+The Fietsboek data lives in two places: Track and account metadata is saved in
+the database, while GPX files, images and other "big files" are saved in the
+data directory.
 
 You should refer to the manual of your DBMS to see what the procedure for a
 backup is. Using the preferred way for your DBMS ensures that your backup
 represents a consistent state of the database.
 
+.. note::
+
+    Check :doc:`maintenance-mode` to see how the maintenance mode can be
+    enabled, which should disable most database accesses during the process.
+
 After backing up the database, you should back up the data directory with a
 tool of your choice, for example by using ``tar``, ``rsync`` or a proper backup
 tool like ``borg``:
@@ -82,7 +88,7 @@ specific version:
 
 .. code:: bash
 
-    .venv/bin/pip install "fietsboek==vX.Y.Z"
+    .venv/bin/pip install "fietsboek==X.Y.Z"
 
 Next, we run the data migrations:
 
diff --git a/doc/administration/configuration.rst b/doc/administration/configuration.rst
index 4d33b7f..24c5fdb 100644
--- a/doc/administration/configuration.rst
+++ b/doc/administration/configuration.rst
@@ -2,7 +2,7 @@ Configuration
 =============
 
 The main configuration of Fietsboek is done via ``.ini``-files. By default,
-three such files exist:
+three such files exist, and one will be loaded at a time:
 
 * ``production.ini`` contains the configuration for the production environment.
   It turns off debugging features (as they are a security risk!) and should
@@ -93,8 +93,8 @@ Database Settings
 
 Fietsboek uses three different databases:
 A SQL database for persistent data (like user accounts), a file storage on the
-disk for big files (like images), and a redis server for ephemeral data (like
-cached tiles).
+disk for big files (like GPX files and images), and a redis server for
+ephemeral data (like cached tiles).
 
 Set ``sqlalchemy.url`` to the URL of the SQL database. See the `SQLAlchemy
 documentation
@@ -103,8 +103,8 @@ information on available URL formats. Make sure to install the driver necessary
 to communicate with your database (e.g. ``psycopg2`` for PostreSQL)!
 
 Set ``fietsboek.data_dir`` to the directory for data uploads. This directory
-must be writable by the Fietsboek process, as Fietsboek will save track images
-in there.
+must be writable by the Fietsboek process, as Fietsboek will save track data in
+there.
 
 Set ``redis.url`` to the URL of the redis instance. See the `redis module
 documentation
@@ -133,7 +133,7 @@ accepted:
   standard output. Should not be used in production, as no emails would ever
   arrive.
 * ``smtp://host:port`` use the given SMTP server (without transport encryption!)
-* ``smtp+ssl://host:port`` use the given SMTP server over a SSL connection
+* ``smtp+ssl://host:port`` use the given SMTP server over a SSL connection.
 * ``smtp+starttls://host:port`` use the given SMTP server and the STARTTLS
   command to start an encrypted channel.
 
@@ -192,11 +192,11 @@ You can add custom tile layers in the following way:
     # public
     fietsboek.tile_layer.ID.access = public
 
-``ID`` must be an alphanumerical identifier.
+``ID`` must be an alphanumerical identifier of your choosing.
 
 By default, Fietsboek will proxy all tile requests through the Fietsboek
-instance. While this can slow down the user experience, it has the following
-benefits:
+instance. While this can slow down the user experience and increase the load on
+your server, it has the following benefits:
 
 * Your users' IPs stay private and protected, as no third party is contacted.
   The tile servers will only see the IP from the Fietsboek server.
@@ -239,15 +239,15 @@ default behavior.
 
 .. note::
 
-    The ``hittekaart.autogenerate`` has no effect on the ``fietsctl
+    The ``hittekaart.autogenerate`` setting has no effect on the ``fietsctl
     hittekaart`` command. You can always use ``fietsctl`` to generate heat maps
-    for specific users!
+    manually!
 
 .. warning::
 
     Depending on the geospatial area that a user covers with their tracks, an
-    overlay map can get relatively large (~100 MiB for mine). Keep that in mind
-    when hosting a larger number of users.
+    overlay map can get relatively large (in my case ~100 MiB). Keep that in
+    mind when hosting a larger number of users.
 
 An example configuration excerpt can look like this:
 
diff --git a/doc/administration/cronjobs.rst b/doc/administration/cronjobs.rst
index a7d1a95..c2939c8 100644
--- a/doc/administration/cronjobs.rst
+++ b/doc/administration/cronjobs.rst
@@ -9,14 +9,20 @@ keep the instance running smoothly:
 * Tracks that are not present in the cache should have their cache entry
   populated by pre-calculating their length/uphill/downhill/… values. This
   makes accessing those values faster when a user requests the track's details.
+* If enabled, heatmaps/tilehunts should be generated.
 
 Fietsboek comes with a script to deal with those jobs: ``fietscron``. You can
 run it like this::
 
     fietscron -c path_to_config.ini
 
+The script is designed to be "smart", meaning that it splits the long tasks
+(such as heatmap generation) over multiple runs, and it should work without
+additional configuration.
+
 You can use any mechanism you like to run this command at pre-defined intervals
-(e.g. once an hour). You can find information about this in various sources:
+(e.g. once an hour). You can find information about this in various sources,
+depending on your system setup:
 
 * https://wiki.archlinux.org/title/Systemd/Timers
 * https://wiki.archlinux.org/title/Cron
diff --git a/doc/administration/custom-pages.rst b/doc/administration/custom-pages.rst
index db92c49..fbc3121 100644
--- a/doc/administration/custom-pages.rst
+++ b/doc/administration/custom-pages.rst
@@ -8,8 +8,8 @@ information or similar things on a website. Or you simply want to add some
 information about your instance of Fietsboek, links to other sites, ...
 
 Such pages can not be provided by Fietsboek out of the box, as they are very
-customized to the particular installation. However, Fietsboek provides a way to
-include custom static pages. Those pages have the benefit of being embedded in
+tailored to the particular site. However, Fietsboek provides a way to include
+custom static pages. Those pages have the benefit of being embedded in
 Fietsboek's menu and layout, so they don't look out of place and can easily be
 found.
 
diff --git a/doc/administration/installation.rst b/doc/administration/installation.rst
index fd0def5..c21af59 100644
--- a/doc/administration/installation.rst
+++ b/doc/administration/installation.rst
@@ -50,17 +50,41 @@ Installing the Python Modules
 -----------------------------
 
 The Python package manager takes care of installing all dependencies, all you
-need to do is tell it to install Fietsboek:
+need to do is tell it to install Fietsboek. How exactly depends on your way of
+acquiring Fietsboek.
+
+Via PIP
+^^^^^^^
+
+Fietsboek is available in the Python Package Index as `fietsboek
+<https://pypi.org/project/fietsboek/>`__ and can be installed directly via
+``pip``:
 
 .. code:: bash
 
-    # Assuming that we are in the Fietsboek folder
-    .venv/bin/pip install .
-    # Alternatively
-    .venv/bin/pip path/to/fietsboek/repository
+    .venv/bin/pip install fietsboek
+
+Via Git
+^^^^^^^
+
+If you prefer to work with the source version (e.g. for development purposes),
+you should use Git to clone the repository from one of its mirrors:
+
+* Main on Gitlab: https://gitlab.com/dunj3/fietsboek
+* Mirror on Codeberg: https://codeberg.org/dunj3/fietsboek
+
+.. code:: bash
+
+    git clone https://gitlab.com/dunj3/fietsboek
+    .venv/bin/pip install ./fietsboek
+    # For development, you can use -e for an editable installation:
+    .venv/bin/pip install -e ./fietsboek
+
+Optional: Install lxml
+^^^^^^^^^^^^^^^^^^^^^^
 
-Optionally, you can install ``lxml``, which provides a faster XML parser to
-process the GPX files:
+In any case, you can optionally install ``lxml``, which provides a faster XML
+parser to process the GPX files:
 
 .. code:: bash
 
diff --git a/doc/administration/maintenance-mode.rst b/doc/administration/maintenance-mode.rst
index d02e27a..30a273c 100644
--- a/doc/administration/maintenance-mode.rst
+++ b/doc/administration/maintenance-mode.rst
@@ -7,7 +7,7 @@ with the data. Deactivating your instance avoids any "race issues" or accesses
 to the database and such, which might be in inconsistent states.
 
 To help with this situation, fietsboek provides a *maintenance mode*. This
-allows you to deactivate fietsboek without having to fiddle with your webserver
+allows you to deactivate fietsboek without having to change with your webserver
 settings.
 
 In the maintenance mode, fietsboek will reply to any HTTP request with a ``503
@@ -16,8 +16,8 @@ Service Unavailable`` response, and won't process the requests further.
 .. note::
 
     The maintenance mode is implemented early in fietsboek, however if you have
-    custom HTTP proxies or other WSGI middleware between fietsboek and the
-    outside world, the maintenance mode will not affect those.
+    custom HTTP proxies, caches or other WSGI middleware between fietsboek and
+    the outside world, the maintenance mode will not affect those.
 
     In those cases, it might be better to deactivate the whole pipeline,
     depending on the setup and the middleware used — at least if those also
@@ -25,17 +25,17 @@ Service Unavailable`` response, and won't process the requests further.
 
 In addition to not replying to HTTP requests, ``fietscron`` will also respect
 the maintenance mode and do nothing. This is to avoid accidental interference
-with long tasks like updating, such that a cronjob doesn't access data in an
-invalid state.
+with long tasks like updating, such that a badly-timed cronjob doesn't access
+data in an invalid state.
 
-Unlike ``fietscron`` and the HTTP requests, ``fietsctl`` and ``fietsupdate``
+Unlike ``fietscron`` and the web interface, ``fietsctl`` and ``fietsupdate``
 will **continue to work**.
 
 Controlling the Maintenance Mode
 --------------------------------
 
 You can enable and disable the maintenance mode using the ``fietsctl`` script.
-To enable the mode, simply pass a reason (that will be shown to users) to
+To enable maintenance, simply pass a reason (that will be shown to users) to
 ``fietsctl maintenance-mode``::
 
     fietsctl -c production.ini maintenance-mode "Updating the instance"
diff --git a/doc/administration/upgrading.rst b/doc/administration/upgrading.rst
index 2b69e4c..c5e899d 100644
--- a/doc/administration/upgrading.rst
+++ b/doc/administration/upgrading.rst
@@ -44,10 +44,17 @@ new additional dependencies:
 
 .. code:: bash
 
-    .venv/bin/pip install .
+    .venv/bin/pip install path/to/fietsboek/source
 
-This step is similar to the command that you used when installing Fietsboek
-initially.
+If you downloaded Fietsboek from PyPI, you may need to tell ``pip`` explicitely
+to upgrade. Otherwise it will simply say that the package is already installed:
+
+.. code:: bash
+
+    .venv/bin/pip install --upgrade fietsboek
+
+In general, this step is similar to the command that you used when installing
+Fietsboek initially.
 
 Note that removed dependencies are not automatically removed. It might be worth
 to start with a clean virtual environment from time to time to clear out old
@@ -120,7 +127,7 @@ Restoring Data: Downgrading
 If you do not have old backups of your data, you can use ``fietsupdate`` to
 convert your data from the new format to the old one. Please note that the
 upgrade process can not always be undone: If an update deletes data, even the
-downgrade cannot fix it. In such cases, the only way to restore the data is
+downgrade cannot undo it. In such cases, the only way to restore the data is
 through a backup.
 
 To use ``fietsupdate`` to downgrade your data, run the following command,