Prepare first 2.x-compatible release

README.md

@@ -2,13 +2,57 @@
 
 ![Tests](https://github.com/rdmorganiser/rdmo-catalog/actions/workflows/tests.yaml/badge.svg)
 
-The repository holds XML files that can be imported into RDMO. They contain different kinds of information like for example the domain model, question catalogs or optionsets.
+This repository contains all content objects (catalogs, attributes, options, conditions, views, tasks) to be used with the DMP software [RDMO](https://github.com/rdmorganiser/rdmo)
 
-The files that are officially provided by the RDMO project are in the `rdmorganiser` folder. We recommend to import these files to be able to make use of the official domain model, options, tasks and conditions. *Note that parts of these data are required to import user content because RDMO user's question catalogs may refer to parts of the official data*.
+The content officially curated by the [RDMO Consortium](https://rdmorganiser.github.io/Community/) is in the [`rdmorganiser`](./rdmorganiser) folder. We recommend to import these files to be able to make use of the official domain model, options, tasks and conditions. *Note that parts of these data are required to import user content because RDMO user's question catalogs may refer to parts of the official data*.
 
-Content shared by RDMO Users can be found under `shared`. There may be multiple files in a folder like for example conditions, options and questions. Files in the same folder belong together. All of them should be imported. Please pay attention to the order in which you import files. Question catalogs referring to other content should be imported at last.
+Content shared by RDMO Users can be found under [`shared`](./shared). There may be multiple files in a folder like for example conditions, options and questions. Files in the same folder belong together: all of them should be imported.
 
-Different scripts are located in `tools`. These are interesting for people maintaining this repo.
+Please pay attention to the order in which you import files. Question catalogs referring to other content should be imported at last. See the following section for details.
+
+Different scripts are located in [`tools`](./tools). These are interesting for people maintaining this repo.
+
+# How to install content
+
+The RDMO content objects (catalogs, attributes, options, conditions, views, tasks) depend on each other, as shown in the [documentation](https://rdmo.readthedocs.io/en/latest/management/data-model.html).
+
+In particular, the installation of question catalogues requires the newest version of attributes, optionsets and conditions.
+
+Therefore we suggest this sequence to install content in a RDMO instance:
+
+## Via the RDMO web interface
+
+Management --> Attributes --> Import <domain_file>.xml
+Management --> Conditions --> Import <conditions_file>.xml
+Management --> Option sets --> Import <options_file>.xml
+Management --> Conditions --> Import <conditions_file>.xml # yes, again
+Management --> Questions --> Import <catalog_file>.xml
+Management --> Tasks --> Import <tasks_file>.xml
+Management --> Views --> Import <views_file>.xml
+
+REMARK: If the chosen catalog is available as a **full XML**, it already includes the necessary attributes, conditions and options.
+
+## Via a Python script
+
+```python
+./manage.py import /<path/to/domain>/rdmo.xml
+./manage.py import /<path/to/conditions>/rdmo.xml
+./manage.py import /<path/to/options>/rdmo.xml
+./manage.py import /<path/to/conditions>/rdmo.xml            # yes, again
+./manage.py import /<path/to/questions>/<chosen_catalog>.xml
+./manage.py import /<path/to/tasks>/<chosen_task>.xml
+./manage.py import /<path/to/views>/<chosen_view>.xml
+```
+
+Use the same order when importing over the RDMO web interface.
+
+Please note that the master branch will only work with the latest version of RDMO. If you need the xml files for an older version, please browse the releases or contact us.
+
+To indent the XML files use:
+
+```bash
+for f in *.xml; do xmllint --format $f > /tmp/$f; mv /tmp/$f $f; done
+```
 
 ## Issues