Improve documentation

README.md

@@ -1,6 +1,12 @@
 # LIDIA Browser: Linguistic Diagnostics explorer
 
-This project fetches bibliographic entries and annotations from the LinguisticDiagnostics Zotero group library, and allows to browse and search them.
+This is the source code for the [LIDIA Annotation Browser](https://lidia.hum.uu.nl/) website.
+The annotation browser is a companion to the [LIDIA Zotero plugin](https://github.com/CentreForDigitalHumanities/lidia-zotero) for LIDIA, a pilot project for annotating linguistic diagnostics.
+
+It is a Django project containing two apps:
+
+- The `sync` app contains management commands and logic for fetching publication and annotation data from a Zotero library via the Zotero API using [pyzotero](https://github.com/urschrei/pyzotero).
+- The `lidia` app contains functions for converting LIDIA YAML annotations to Django structures, and provides a browse/search interface using the Django Admin.
 
 
 ## Installation
@@ -9,7 +15,8 @@ Install the dependencies:
 
     pip install -r requirements.txt
 
-Create a file `.env` in the repository root with your Zotero library and authentication details:
+Create a file `.env` in the repository root with your Zotero library and authentication details.
+See the [pyzotero quickstart](https://github.com/urschrei/pyzotero#quickstart) for where to get a Zotero API key and find your library ID.
 
 ```sh
 ZOTERO_LIBRARY_ID=12345
@@ -31,5 +38,12 @@ python manage.py migrate
 python manage.py runserver
 python manage.py sync
 python manage.py populate
+python manage.py runserver
 ```
 
+You can remove raw sync data or converted sync data from the database using the `--refresh` option:
+
+```sh
+python manage.py sync --refresh
+python manage.py populate --refresh
+```