updated documentation

Author: jspaaks

.mlc-config.json

@@ -24,5 +24,6 @@
     "replacementPatterns": [{
         "pattern": "^/",
         "replacement": "https://github.com/research-software-directory/research-software-directory/blob/master/"
-    }]
+    }],
+    "retryOn429": true
 }

README.md

@@ -60,17 +60,20 @@ To quickly get a running Research Software Directory up and running on your loca
     ```
 Go to [http://localhost](http://localhost) (disregard certificate warning) to see the Research Software Directory
 website. You should be able to see all non-authenticated pages, but editing data or harvesting data from external
-sources won't work. To bring up the website with all bells and whistles, read on in the next chapters.
-
-## Use cases
-
-1. [Contributing](/.github/CONTRIBUTING.md)
-1. [Running an instance with your own data sources](/docs/configure.md)
-1. [Entering your own data](/docs/instruction/README.md)
-1. [Changing the look and feel](/docs/customize.md)
-1. [Finding your way: Research Software Directory services](/docs/services.md)
-1. [Documentation for developers](/docs/dev.md)
-1. [Documentation for maintainers](/docs/maintaining.md)
-1. [Hosting your instance online](/docs/hosting.md)
-1. [Running an instance of the Research Software Directory in production](/docs/production.md)
-1. [Security concerns](/docs/security.md)
+sources won't work. To bring up the website with all bells and whistles, refer to selected resources from the list
+below.
+
+## Further resources
+
+<!-- see also docs/README.md -->
+
+1. [Entering data about your software in an existing instance](./docs/entering-data.md)
+1. [Configuring your instance to use your own data sources](./docs/configuring-your-instance-to-use-your-own-data-sources.md)
+1. [Changing the look and feel](./docs/changing-the-look-and-feel.md)
+1. [Hosting your instance online](./docs/hosting.md)
+1. [Running an instance of the Research Software Directory in production](./docs/production.md)
+1. [Finding your way: Research Software Directory services](./docs/services-overview.md)
+1. [Documentation for developers](./docs/documentation-for-developers.md)
+1. [Documentation for maintainers](./docs/documentation-for-maintainers.md)
+1. [Security concerns](./docs/security.md)
+1. [Contributing](./.github/CONTRIBUTING.md)

docs/README.md

@@ -0,0 +1,14 @@
+# Contents
+
+<!-- see also bottom of main readme -->
+
+1. [Entering data about your software in an existing instance](./docs/entering-data.md)
+1. [Configuring your instance to use your own data sources](./docs/configuring-your-instance-to-use-your-own-data-sources.md)
+1. [Changing the look and feel](./docs/changing-the-look-and-feel.md)
+1. [Hosting your instance online](./docs/hosting.md)
+1. [Running an instance of the Research Software Directory in production](./docs/production.md)
+1. [Finding your way: Research Software Directory services](./docs/services-overview.md)
+1. [Documentation for developers](./docs/documentation-for-developers.md)
+1. [Documentation for maintainers](./docs/documentation-for-maintainers.md)
+1. [Security concerns](./docs/security.md)
+1. [Contributing](./.github/CONTRIBUTING.md)

docs/about.md

@@ -1,4 +1,4 @@
-# Configuring the Research Software Directory
+# Using your own data sources
 
 The research software directory is configured using a file with environment
 variables called `.env`. An example config file

docs/customize.md renamed to docs/changing-the-look-and-feel.md

@@ -12,7 +12,7 @@ git clone https://github.com/<your-github-organization>/research-software-direct
 
 ## Try it out, step 2/3: Configure
 
-See [configure.md](configure.md)
+See section [Using your own data sources](using-your-own-data-sources.md).
 
 ## Try it out, step 3/3: Start the complete stack using [docker-compose](https://docs.docker.com/compose/)
 

docs/configure.md renamed to docs/configuring-your-instance-to-use-your-own-data-sources.md

@@ -42,7 +42,7 @@ selecting them via the dropdown list in the Admin interface of the Research Soft
 
 ### Output and impact
 
-The items on the  dropdown list are harvested periodically from the
+The items on the dropdown list are harvested periodically from the
 [Netherlands eScience Center group on
 Zotero](https://www.zotero.org/groups/1689348). For reference, Zotero is the
 place where we keep track of NLeSC's _output_ and _impact_:
@@ -107,6 +107,8 @@ blue ``+`` symbol.
 1. Optionally, fill in the person's email address
 1. Optionally, provide an image of the person
 1. **Don't forget** to click ``Save`` when you're done.
+1. Refer to section [_Delays_](#delays) and section [_The query
+trick_](#the-query-trick) to know when you get to see your changes.
 
 ## How do I add a new ``Mention``?
 
@@ -128,6 +130,8 @@ blue ``+`` symbol.
       produced with NLeSC funding), or as "impact" (the mention was produced without
       NLeSC funding, for example when a paper cites code that NLeSC created).
 1. **Don't forget** to click ``Save`` when you're done.
+1. Refer to section [_Delays_](#delays) and section [_The query
+trick_](#the-query-trick) to know when you get to see your changes.
 
 ## How do I add a new ``Organization``?
 
@@ -143,7 +147,8 @@ clicking the blue ``+`` symbol.
    1. Organizations often offer the source files for their logos via a link on
       their website, usually named something like "Press" or "House style".
 1. **Don't forget** to click ``Save`` when you're done.
-1. You may need to refresh the page to see newly added items appear in the left pane
+1. Refer to section [_Delays_](#delays) and section [_The query
+trick_](#the-query-trick) to know when you get to see your changes.
 
 ## How/when do I get to see my changes?
 
@@ -161,12 +166,12 @@ If your change only involves the Research Software Directory's Admin interface,
 for example when you add a pre-existing ``Mention`` to a ``Software`` and press
 ``Save``, the corresponding database collection is updated immediately but the
 data needed for populating the product page template is collected at intervals.
-Again, refer to the schedule at
+Refer to the schedule at
 [https://research-software.nl/schedule](https://research-software.nl/schedule) and look for the
 ``python app.py resolve`` task.
 
 If your change involves an external data source, e.g. you have new commits on
-GitHub, or a new release on Zenodo, you will only see the resulting data show up
+GitHub, a new release on Zenodo, or you've added an entry to Zotero, you will only see the resulting data show up
 in the Research Software Directory after the corresponding data is harvested.
 Check [https://research-software.nl/schedule](https://research-software.nl/schedule) and look for
 the ``python app.py harvest commits`` and ``python app.py harvest citations``