docs(wdqs): details about the empty sync issue (#759)

* docs(wdqs): details about the empty sync issue

This adds some documentations about the issue where WDQS crashes when
restarted with an empty database that never synced entities from
MediaWiki.

https://phabricator.wikimedia.org/T354266

* small edits to the new text

---------

Co-authored-by: Dan Shick <dan.shick@wikimedia.de>

build/WDQS/README.md

@@ -200,16 +200,27 @@ Hooking into the internal filesystem can extend the functionality of this image.
 
 ### Updater keeps restarting
 
-In some situations the WDQS Updater enters a restart loop. A workaround is to start the updater once with manual `--init` `--start` parameters for the current day.
+In some situations the WDQS Updater enters a restart loop, e.g., when restarted without containing any entities. When you restart a freshly installed instance, you will encounter this issue.
 
-In the Docker Compose example provided above, you might run:
+A workaround is to start the updater once with manual `--init` `--start` parameters. This forces it to sync data from MediaWiki for the current day.
+
+In the Docker Compose example provided above, you might use the commands and instructions supplied below. This will also fix the problem in a Wikibase Suite Deploy instance.
 
 ```sh
+# Stop the stock updater
 docker compose stop wdqs-updater
+
+# Start an updater with force sync settings
 docker compose run --rm wdqs-updater bash '/wdqs/runUpdate.sh -h http://"$WDQS_HOST":"$WDQS_PORT" -- --wikibaseUrl "$WIKIBASE_SCHEME"://"$WIKIBASE_HOST" --conceptUri "$WIKIBASE_SCHEME"://"$WIKIBASE_HOST" --entityNamespaces "$WDQS_ENTITY_NAMESPACES" --init --start $(date +%Y%m%d000000)'
+
+# As soon as you see "Sleeping for 10 secs" in the logs, press CTRL-C to stop it again
+
+# Start the stock updater again
 docker compose start wdqs-updater
 ```
 
+As soon as the updater has synced the first entity from MediaWiki, the issue should disappear.
+
 ## Source
 
 This image is built from this [Dockerfile](https://github.com/wmde/wikibase-release-pipeline/blob/main/build/WDQS/Dockerfile).

deploy/README.md

@@ -322,6 +322,10 @@ It is possible to migrate an existing Wikibase installation to WBS Deploy. The g
  - Regenerate the WDQS database
  - Regenerate the Elasticsearch database
 
+### My WDQS Updater keeps crashing, what can I do?
+
+Check out the known issue in the [WDQS README](../build/WDQS/README.md#Known-issues). You may find your solution there in the form of a workaround.
+
 ### Do you recommend any VPS hosting providers?
 
 As of this writing, we can offer no specific recommendations for VPS providers to host Wikibase Suite. The suite has been tested successfully on various providers; as long as the [minimum technical requirements](#hardware) are met, it should run as expected.