From 10c93d7b4412441dcaba4351a35578fcee0807f9 Mon Sep 17 00:00:00 2001
From: Maximilian Moser <maximilian.moser@tuwien.ac.at>
Date: Tue, 17 Sep 2024 20:20:53 +0200
Subject: [PATCH] Update README

---
 README.rst | 65 ++++++++++++++++++++++++++++++++----------------------
 1 file changed, 39 insertions(+), 26 deletions(-)

diff --git a/README.rst b/README.rst
index 28ddf70..453d145 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,5 @@
 ..
-    Copyright (C) 2020-2022 TU Wien.
+    Copyright (C) 2020-2024 TU Wien.
 
     Invenio-Config-TUW is free software; you can redistribute it and/or
     modify it under the terms of the MIT License; see LICENSE file for more
@@ -9,55 +9,68 @@
  Invenio-Config-TUW
 ====================
 
-Invenio module for tweaking InvenioRDM to the needs of TU Wien.
+Invenio package for tweaking InvenioRDM to the needs of TU Wien.
 
-We use this module to customize the following:
+The following list is a quick overview of the most relevant customizations happening in this package:
 
+* Configuration values
 * Permission policies
 * OIDC authentication handling
 * E-Mail notification on errors
-* Configuration values
+* User profile extension
+* Integration with other TU Wien services
 
 
 Details
 =======
 
+Configuration values
+--------------------
+
+The primary purpose of this Invenio package is to provide some baseline configuration for InvenioRDM to suit deployment at TU Wien.
+These updated configurations include (but are not limited to) setting default values for record metadata and enabling access requests for restricted records per default.
+
+
 Permission policies
 -------------------
 
-Currently, we are still operating on a friendly-user basis.
-That is, while we cannot lose any data that has been uploaded by our users, we do not
-allow every registered user to create record drafts, upload data, or publish records
-from the get-go.
-Instead, we require users to have the ``trusted-user`` role in order to be able to
-create record drafts and upload data.
-Similarly, we have the ``trusted-publisher`` role as a requirement for publishing
-records.
-Generally, these roles have to be assigned to users manually by an administrator.
+InvenioRDM is not just some sort of cheap storage platform where users can upload their data and update it at any time.
+Instead, it is a platform intended to host digital objects that get [DOIs](https://www.doi.org/) assigned.
+Since the idea behind DOIs (and persistent identifiers in general) is to point at the same content over time, it does not allow users to change the files after publication.
 
-On the test system, we give out these permissions automatically if we detect that a
-newly registered user is an employee of TU Wien.
+This is one of the unique features that the system offers that may not be immediately obvious to users.
+To make sure that users understand the implications of using the system, we require a brief communication between the users and operators.
+
+In contrast to vanilla InvenioRDM, having an account is not enough to create uploads in our system.
+Instead, the creation of records requires the ``trusted-user`` role, which typically has to be given out by administrators.
+
+Also, communities can be quite confusing in the beginning.
+Thus, we restrict the creation of new communities for non-administrators.
 
 
 OIDC authentication handling
 ----------------------------
 
-Because we have some special requirements regarding the authentication and signup
-process, we have customized some of the handler functions for the OAuth client
-that's integrated in InvenioRDM.
-These customizations are contained in the files in ``auth/``.
+We do not want to handle certain aspects like password management of user management in our system.
+Instead, we offload authentication to a separate service, with which InvenioRDM communicates via OIDC.
+Sometimes we have slightly non-standard requirements, which are satisfied by the authentication handler logic in this package.
 
 
 E-Mail notification on errors
 -----------------------------
 
-This module defines a custom log handler for error-level logs which sends out
-notifications as e-mail to a set of configured recipient addresses.
+This module defines a custom log handler for error-level logs which sends out notifications as e-mail to a set of configured recipient addresses.
 
 
-Configuration values
---------------------
+User profile extension
+----------------------
+
+We forgot to secure the rights to curate metadata for uploads in our system in the first version of the terms of use.
+So instead, we extended the user profiles to collect consent for curation individually per user.
+
+
+Integration with other TU Wien services
+---------------------------------------
 
-Last but not least, we also set some default configuration values for deployments
-of InvenioRDM at TU Wien.
-The relevant files here are ``config.py`` and ``ext.py``.
+One of the benefits of hosting InvenioRDM as an institutional repository is that it enables some conveniences by integrating with the local environment more.
+For example, we integrate with [TISS](https://tiss.tuwien.ac.at/) by periodically querying it for TU Wien employees and adding their names to the controlled vocabulary of known ``names``.
-- 
GitLab