tidy docs

Author: aaxelb

README.md

@@ -8,7 +8,7 @@ SHARE/trove (aka SHARtrove, shtrove) is is a service meant to store (meta)data y
 
 note: this codebase is currently (and historically) rather entangled with [osf.io](https://osf.io), which has its shtrove at https://share.osf.io -- stay tuned for more-reusable open-source libraries and tools for working with (meta)data
 
-see [how-to docs](./how-to/) for help setting up and using various things
+see [how-to docs](./how-to/README.md) for help setting up and using various things
 
 see [ARCHITECTURE.md](./ARCHITECTURE.md) for help navigating this codebase
 

how-to/relate-to-osf.md

@@ -103,28 +103,36 @@ could be implemented a variety of ways -- if there were multiple trovesearch str
 (as there was before settling on trovesearch_denorm), can select a non-default one with
 the `indexStrategy` query param)
 
-## OSF-to-shtrove ingestion sequence
+## OSF-thru-shtrove ingestion sequence
 (slightly simplified)
 ```mermaid
 sequenceDiagram
-    participant ms as metadata source
+    box OSF
+    participant oq as queues (rabbitmq)
+    participant od as db (postgres)
+    participant ow as worker (celery)
+    end
     box shtrove
     participant ss as web server
-    participant sd as db
-    participant sw as worker
-    participant sq as queues
+    participant sd as db (postgres)
+    participant sw as worker (celery)
+    participant sq as queues (rabbitmq)
     participant si as indexer
-    participant se as elastic
+    participant se as elasticsearch
     end
-    ms ->> ss: POST /trove/ingest
-    ss ->> sd: save metadata record
+    oq -->> ow: receive update task
+    od <<-->> ow: gather metadata
+    ow ->> ss: POST /trove/ingest
+    ss ->> sd: save ResourceIdentifier(s)
+    ss ->> sd: save Indexcard
+    ss ->> sd: save ResourceDescription(s)
     ss ->> sq: enqueue derive task
-    ss ->> ow: success!
+    ss ->> ow: 201 CREATED (success!)
     sq -->> sw: receive derive task
-    sd <<-->> sw: load metadata record
+    sd <<-->> sw: load ResourceDescription(s)
     sw ->> sd: save DerivedIndexcards
     sw ->> sq: enqueue indexer message
-    sq -->> si: bulk receive indexer messages
-    sd <<-->> si: bulk load metadata
+    sq -->> si: bulk receive messages
+    sd <<-->> si: bulk load metadata records
     si ->> se: bulk index
 ```

how-to/use-the-admin-site.md

@@ -1,4 +1,4 @@
-# how to use the admin ui
+# how to use the admin site
 
 shtrove has a [django admin site](https://docs.djangoproject.com/en/stable/ref/contrib/admin/)
 at `/admin/` that can be used for interacting with the database and managing search indexes

how-to/wrangle-index-strategies.md

@@ -25,10 +25,7 @@ major-version upgrade of elasticsearch) you should instead create a new index st
 3. ensure all services are running up-to-date code (in local dev setup, restart `indexer`, `worker`, and `web`)
 4. in the [shtrove admin site](./use-the-admin-site.md), use `/admin/search-indexes` to setup and backfill the new current version
 5. use the trove api with `indexStrategy` query param (using the full `mystrategy__checksum...` identifier) to test/compare against the prior (default) version
-6. when ready to switch over to use the new version by default, use `/admin/search-indexes`:
-    - 
-6. when ready to switch over use `/admin/search-indexes` to make the updated "current" the new default for searching with that strategy
-7. when ready to delete a prior version, use `/admin/search-indexes`
+6. when ready, use `/admin/search-indexes` to make the new version the default for searching and (when really really ready) to delete the prior version
 
 ## how to set up a new index strategy
 1. add an instance of your `IndexStrategy` subclass to `share.search.index_strategy._AvailableStrategies` with a unique shortname (this should someday be configurable in settings, but is currently hard-coded)