fix: polishing documentation (#37)

Co-authored-by: Anton Baliasnikov <anton.baliasnikov@iohk.io>

documentation/docs/atala-prism/infrastructure/hosted-instances.md

@@ -1,16 +1,16 @@
 # Hosted Instances 
 
-PRISM is designed as a cloud-native technology stack and is available to clients as a *Software-as-a-Service* (SaaS) offering. 
+PRISM is designed as a cloud-native technology stack and is available to clients as a Software-as-a-Service (SaaS) offering. 
 
 Clients and their developers can quickly begin interacting and building upon the SaaS offering without worrying about running an instance themselves.
 
-This section is an introduction to the basics of hosted instances, some details on their architecture and links to instructions for interacting with them.
+This section introduces the basics of hosted instances, some details on their architecture, and links to instructions for interacting with them.
 
 ## Overview
 
 Instances of the PRISM offering are hosted in Amazon Web Services and run within a Kubernetes container execution layer. 
 
-Each instance is single-tenant, has dedicated storage and runs on shared infrastructure - all isolated. 
+Each instance is single-tenant, has dedicated storage, and runs on shared infrastructure - all isolated. 
 
 ![Four single-tenant instances running isolated on shared infrastructure](/img/hosted-instances-overview-1.svg)
 
@@ -26,7 +26,7 @@ Organizations cannot access any other instance apart from their own
 
 Each instance has a dedicated domain name, and API tokens are issued to the organization to manage access. 
 
-All ingress points are protected with TLS using strong cyphers and configuration parameters. 
+All ingress points are protected with TLS using strong ciphers and configuration parameters. 
 
 ### Accessing your dedicated instance
 
@@ -42,25 +42,25 @@ For example, for an environment given the instance-id of `ei30m6d5368w`, its API
 
 :::note 
 
-Atala also prepend a `purpose` flag to instances. This flag indicates if they are development (d), test (t), staging (s), or production (p) instances. The purpose flag is not part of the domain.
+Atala also prepends a `purpose` flag to instances. This flag indicates if they are development (d), test (t), staging (s), or production (p) instances. The purpose flag is not part of the domain.
 
 :::
 
-Atala will provide you with your instance-id and API tokens when you are onboarded. 
+Atala will provide you with your instance-id and API tokens during onboarding.
 
 :::tip Getting more tokens
 
  Atala recommends that you request the creation of additional tokens for each integration/service or human user that you have. Please see [Getting Help](../getting-help) for instructions on how to get in touch with us to request additional API tokens.
 
 :::
 
-An API token must be added to every API call made to non-public endpoints. The API token must be attached using a header in the HTTP requests under they key of `apikey`
+An API token must get added to every API call to non-public endpoints. The API token must be attached using a header in the HTTP requests under the key of `apikey`
 
 ![Example Insomnia window showing `apikey` header being specified](/img/hosted-instances-apikey-header.png)
 
 :::info Public Endpoints
 
-Some endpoints must be unprotected in that they do not require authentication. These endpoints must be accessible by everyone for the agent to interact with the wider identity ecosystem which requires interopability with common standards. A good example of a public endpoint is the DIDComm endpoint - which - must be able to recieve messages from client devices which have no fixed address and whose agents do not spknow of the PRISM authentication requirement.
+Some endpoints must be unprotected in that they do not require authentication. These endpoints must be accessible by everyone for the agent to interact with the wider identity ecosystem which requires interoperability with common standards. A good example of a public endpoint is the DIDComm endpoint - which - must be able to receive messages from client devices with no fixed address and whose agents do not know of the PRISM authentication requirement.
 
 :::
 
@@ -81,17 +81,18 @@ Each instance exposes many HTTP routes, allowing an organization to consume the
  **PRISM Cloud Agent**, which sits at the core of every PRISM instance, provides:
   - a *DIDComm v2* endpoint for agent-to-agent communication
   - endpoints to control the configuration and actions of the agent
-  - an endpoint which shows *documentation in Open API Standard* for all available endpoints
+  - an endpoint that shows documentation in Open API Standard for all available endpoints
 
 **PRISM Node** does not provide endpoints that an organization can interact with - it gives internal only gRPC endpoints to the PRISM Cloud Agent for reading and writing to the distributed ledger - Cardano. Please see [PRISM Node](../prism-node) for further details on what this component does and how it works.
 
-Each instance has **Dedicated Relational Storage**, a dedicated instance of a Postgres database. This database is not shared and is accessible from within your tenant only. The database uses authentication with secrets generated by your tenant at the creation time. 
+Each instance has **Dedicated Relational Storage**, a dedicated instance of a Postgres database. This database is not shared and is accessible from within your tenant only. The database uses authentication with secrets your tenant generates during creation time. 
+
 
 ### What else do I need to know about my instance?
 
-Each dedicated instance is hosted within a Kubernetes cluster that spans a single AWS region. This underlying shared infrastructure is highly resilient and self-healing. 
+Each hosted dedicated instance within a Kubernetes cluster spans a single AWS region. This underlying shared infrastructure is highly resilient and self-healing.
 
-Atala currently operates a single region in AWS, based in US East (N. Virginia).
+Atala operates a single AWS region based in US East (N. Virginia).
 
 Each region's Kubernetes cluster runs on EC2 instances spread amongst availability zones. The cluster runs an auto-scaler which creates additional nodes if a failure in one zone should occur.
 

documentation/docs/atala-prism/infrastructure/running-agent-locally.md

@@ -1,14 +1,14 @@
 # Running Agent Locally
 
-The PRISM Cloud Agent can be downloaded and run in a self-hosted way, allowing anyone to run an agent on their computer or server to interact with other agents in the Self-Sovereign Identity (SSI) world.
+The PRISM Cloud Agent can be downloaded and run in a self-hosted way, allowing anyone to run an agent on their computer or server to interact with other agents in the decentralized identity ecossytems.
 
 :::note
 
 The PRISM Cloud Agent Enterprise is only available in managed, hosted instances. Please see [Hosted Instances](hosted-instances) for more details.
 
 :::
 
-This section describes how to get up and running with PRISM Cloud Agent.
+This section describes how to get started with the PRISM Cloud Agent.
 
 :::caution
 
@@ -33,21 +33,21 @@ An agent will be up and running on and accessible on `http://localhost/`
 
 :::info
 
-Detailed instructions on using the `run.sh` script are available in the PRISM Playground project within the `agent/README.md` file.
+Detailed instructions on using the `run.sh` script is available in the PRISM Playground project within the `agent/README.md` file.
 
 :::
 
 ### Exposing PRISM Cloud Agent to the internet
 
-Interacting with other agents requires exposing your agent over the internet. External parties must be able to connect to your instance through a publicly available address without being blocked by security defences like firewalls.
+Interacting with other agents requires exposing your agent over the internet. External parties must be able to connect to your instance through a publicly available address without being blocked by security defenses like firewalls.
 
 Running applications on your computer or server using docker-compose will not expose ports/services to the internet - it will only be available from the host itself and, potentially, the local area network. Additional configuration of your networking layer is required to allow external systems to send messages to your agent.
 
 This guide does not detail the configuration needed to expose the agent to the internet via the management of the networking layer. The networking design is an advanced topic and depends upon the computing environment in which you operate your agent. 
 
-As an alternative, for quickly getting up and running with a local PRISM Cloud Agent, we recommend using a tunnelling solution such as [ngrok](https://ngrok.com/).
+As an alternative, for quickly getting up and running with a local PRISM Cloud Agent, we recommend using a tunneling solution such as [ngrok](https://ngrok.com/).
 
-ngrok is a software package you can download and install that, when executed, creates an externally accessible tunnel to your machine without the need for complex networking configuration such as firewall management or port forwarding. 
+ngrok is a software package you can download and install that when executed, creates an externally accessible tunnel to your machine without the need for complex networking configuration such as firewall management or port forwarding. 
 
 Ngrok assigns a unique domain name to each tunnel created with it, which lives for the duration that ngrok is running. This domain is the externally accessible ingress point for other agents to communicate with your agent with 
 
@@ -109,13 +109,13 @@ After you have created a tunnel - run the PRISM Cloud Agent using the following
 run.sh --ngrok
 ```
 
-The `DIDComm Service Endpoint` in your agent will be set as the ngrok tunnel address. Interactions with other agents will result in communication flowing back into your agent.
+The `DIDComm Service Endpoint` in your agent will need to be the ngrok tunnel address. Interactions with other agents will result in communication flowing back into your agent.
 
 #### Additional information
 
 The free account tier of ngrok will provision a random domain every time you start a ngrok tunnel. A tunnel may be interrupted by network failures and restarts of your system, resulting in the domain name changing.
 
-As the domain name changes, the location of your agent changes and other agents may send messages to the wrong place.
+As the domain name changes, the location of your agent changes, and other agents may send messages to the wrong place.
 
 **Please consider subscribing to a commercial plan with ngrok for persistent domain names [or configure your networking layer manually to allow ingress] if you need the agent to always be accessible in one place.
 **
@@ -128,4 +128,4 @@ The status of an active ngrok tunnel is shown in the ngrok web interface accessi
 
 The PRISM Cloud Agent docker-compose files include running and configuring an API Gateway - APISIX. An API Gateway is required when running the PRISM Cloud Agent as it is built as a microservice architecture and comprises multiple services running on different network ports.
 
-The API Gateway unifies these different services into a single ingress plane where a single port is exposed rather than many. Using APISIX as an API Gateway provides security and protection to prevent unauthorized access.
+The API Gateway unifies these different services into a single ingress plane where a single port is exposed rather than many. We use APISIX as an API Gateway that provides security and protection to prevent unauthorized access.

documentation/docs/atala-prism/overview.md

@@ -1,21 +1,21 @@
 # Overview
 
-The Atala PRISM offering comprises the following core components:
+The Atala PRISM suite contains the following core components:
 
-- PRISM Cloud Agent, a fully featured cloud agent used for interacting with other agents in the realm of Self-Sovereign-Identity (SSI) in a standards-based and interoperable way
-- PRISM Node, a *Verifiable Data Registry* (VDR) which provides on-chain persistence using the Cardano blockchain.
-- PRISM Mediator, which allows mobile applications to route messages to and from Prism Agents
-- PRISM Cloud Agent Enterprise - built on top of the fully featured PRISM Cloud Agent as its foundation, providing additional capabilities and enterprise-ready business controller logic
+- PRISM Cloud Agent, a fully featured cloud agent used for interacting with other identity agents in a standards-based and interoperable way
+- PRISM Node, a [Verifiable Data Registry](/documentation/docs/concepts/glossary.md#verifiable-data-registry) (VDR) which provides on-chain persistence using the Cardano blockchain.
+- PRISM Mediator allows mobile applications to route messages to and from PRISM Agents
+- PRISM Cloud Agent Enterprise, built on top of the fully featured PRISM Cloud Agent as its foundation, provides additional capabilities and enterprise-ready business controller logic
 
-Atala offers a hosted service for PRISM, which provides a dedicated - single-tenant instance - powered by the above components.
+Atala offers a hosted service for PRISM, which provides a dedicated, single-tenant instance powered by the above components.
 
-Atala builds its services using a set of functionally decomposed building blocks which are re-usable libraries with strong domain context bounds.  
+Atala builds its services using a set of functionally decomposed building blocks which are re-usable libraries with strong domain context bounds.
 
 For more information regarding each component, please see the following links:
-  - For the fully featured PRISM Cloud Agent, please see [PRISM Cloud Agent](prism-cloud-agent/overview)
-  - For details on the building-blocks, please see [Building Blocks](prism-cloud-agent/building-blocks)
-  - For the Verifiable Data Registry based upon Cardano, please see [PRISM Node](prism-node)
-  - For how Atala host it's dedicated instances, please see [Hosted Instances](infrastructure/hosted-instances)
+  - [PRISM Cloud Agent](prism-cloud-agent/overview)
+  - [Building Blocks](prism-cloud-agent/building-blocks)
+  - [PRISM Node](prism-node)
+  - [Hosted Instances](infrastructure/hosted-instances)
 
 Atala PRISM also provides feature-rich SDKs with documentation:
   - For building Apple SSI Applications, please see [Swift SDK](https://swift-docs.atalaprism.io/)