[RND-344] Documentation updates in preparation for 0.2.0. (#94)

* Pointing the instructions to the folder instead of the readme file for clarity

* Modifications to localhost instructions

* Clarification about which .env file(s) to modify

* Markdown cleanup

* Remove obsolete document

* Rewrite main readme

* Additional notes and formatting

* Refactor note on Resource Ids
Formatting

* Typo fix

Co-authored-by: AndonyNS <[email protected]>

Meadowlark-js/backends/meadowlark-opensearch-backend/docker/readme.md

@@ -3,10 +3,10 @@
 :exclamation: This solution should only be used on localhost with proper firewalls around
 external network access to the workstation. Not appropriate for production use.
 
-This Docker Compose file provisions a single node of the OpenSearch search engine and [OpenSearch
-  Dashboard](http://localhost:5601/) (latest versions).
+This Docker Compose file provisions a single node of the OpenSearch search
+engine and [OpenSearch Dashboard](http://localhost:5601/) (latest versions).
 
-### Visualizations in OpenSearch Dashboards
+## Visualizations in OpenSearch Dashboards
 
 Once data starts flowing into OpenSearch, you can setup some basic
 visualizations with the OpenSearch Dashboards. Basic steps:

Meadowlark-js/backends/meadowlark-postgresql-backend/docker/readme.md

@@ -7,9 +7,12 @@ This Docker Compose file provisions a single instance of PostgreSQL 14.
 
 ## Preparatory Steps
 
-You can customize the PostgreSQL startup with three environment variables, which can also
+You can customize startup of the PostgreSQL container with three environment variables, which can also
 be placed into a `.env` file:
 
 * `POSTGRES_USER` (default value: "postgres")
 * `POSTGRES_PASSWORD` (default value: "abcdefgh1!")
 * `POSTGRES_PORT` (default value: 5432)
+
+Note: if you choose different values here, then be sure to use those same values
+in your [meadowlark-fastify](../../../services/meadowlark-fastify) `.env` file.

README.md

@@ -4,21 +4,26 @@
  src="images/cropped-meadowlark-cc-by-nc-4.0-naturenerd_joel.png" align="right"
  width="300">
 
-The Meadowlark code and releases provide a deployable, distributable,
-proof-of-concept for a cloud-native (i.e., built on cloud services)
-implementation of the Ed-Fi API surface. It therefore replicates the data
-collection capabilities of the Ed-Fi ODS/API, but does not replicate the
-database structure and storage of the ODS/API.
+Project Meadowlark is a research and development effort to explore potential for
+use of new technologies, including managed cloud services, for starting up an
+Ed-Fi compatible API.
 
-:no_entry: Warning :no_entry:: this is not for use in production or
-production-like settings.
+While it was originally intended as a proof-of-concept, due to positive feedback
+from the community, it is _beginning to align_ towards production readiness.
+However, the current milestone 0.2.0 release leaves much work yet to be done
+before there is a complete tool that could be used in a pilot test. Pilot
+readiness is the current goal for milestone 0.3.0, which we hope to make
+available before the Ed-Fi Summit in early November, 2022.
+
+See [Project Meadowlark - Exploring Next Generation
+Technologies](https://techdocs.ed-fi.org/x/RwJqBw) in Tech Docs for more
+information on the background and design decisions for this project.
 
 ## Getting Started
 
-* [Deployment on AWS](docs/DEPLOYMENT.md)
 * [Running on Localhost](docs/LOCALHOST.md)
-* [Developer getting started notes](docs/)
-  * [Additional technical details](docs/TECHNICAL.md)
+* [Developer getting started notes](docs/README.md)
+* [Additional technical details](docs/TECHNICAL.md)
 
 ## Legal Information
 

docs/LOCALHOST.md

@@ -6,15 +6,25 @@ Instructions for running a local "developer" environment on localhost:
 2. Enable [Yarn](https://yarnpkg.com/getting-started/install) as the package manager
 3. Install [Docker Desktop](https://www.docker.com)
 4. Review the [General Docker Guidance](../Meadowlark-js/docker/using-docker.md) for Meadowlark
-5. Initialize a backend technology:
-   * **MongoDB**: Start a MongoDB cluster in Docker
-     ([instructions](../Meadowlark-js/backends/meadowlark-mongodb-backend/docker/readme.md)).
-   * **PostgreSQL**: Start PostgreSQL in Docker ([instructions](../Meadowlark-js/backends/meadowlark-postgresql-backend/docker/readme.md)).
-6. Initialize OpenSearch by starting it up in Docker
-   ([instructions](../Meadowlark-js/backends/meadowlark-opensearch-backend/docker/readme.md)).
-7. Setup environment variables for running [meadowlark-fastify](../Meadowlark-js/services/meadowlark-fastify/)
-   service. The folder has an example.env file with all settings needed to run the service, the easiest way to set your environment variables is to duplicate this file in the folder and rename the file to .env
-   1. Review the settings in the .env file to see what values, if any, to change. In particular:
-      * DOCUMENT_STORE_PLUGIN - Make sure your chosen backend is uncommented and comment out the rest
-      * QUERY_HANDLER_PLUGIN - Having this value uncommented allows for querying from Opensearch
-      * LISTENER1_PLUGIN - Having this value uncommented will allow Meadowlark documents to flow to OpenSearch
+5. The Meadowlark runtime currently requires running either PostgreSQL or
+   MongoDB as the primary datastore, and OpenSearch as a secondary storage for
+   high-performance queries. Before running the Meadowlark code, startup local
+   instances of the data stores that you wish to use. The repository comes with
+   Docker compose files for easily starting up all three. Either run
+   `eng/docker.ps1` in PowerShell to start all three data stores at the same
+   time (using default configuration), or see the individual directories if you
+   wish to customize or to run `docker compose` directly in the directory
+   containing the compose file:
+   * [MongoDB](../Meadowlark-js/backends/meadowlark-mongodb-backend/docker)
+   * [PostgreSQL](../Meadowlark-js/backends/meadowlark-postgresql-backend/docker)
+   * [OpenSearch](../Meadowlark-js/backends/meadowlark-opensearch-backend/docker)
+6. Setup environment variables for running
+   [meadowlark-fastify](../Meadowlark-js/services/meadowlark-fastify/) service.
+   The folder has an `example.env` file with all settings needed to run the
+   service; the easiest way to set your environment variables is to duplicate
+   this file in the folder and rename the file to `.env`. Review the settings in
+   the `.env` file to see what values, if any, to change. In particular:
+      * `DOCUMENT_STORE_PLUGIN` - Make sure your chosen backend is uncommented
+        and comment out any others.
+      * `QUERY_HANDLER_PLUGIN` and `LISTENER1_PLUGIN` - Uncomment these two for
+        GET query support using OpenSearch.