From bead429338bd031a42207feca3e1cf9a606ad50f Mon Sep 17 00:00:00 2001
From: Eric Maynard <eric.maynard+oss@snowflake.com>
Date: Wed, 2 Oct 2024 16:11:30 -0400
Subject: [PATCH] style-and-copy (#340)

---
 site/content/in-dev/unreleased/_index.md      |  2 +-
 .../configuring-polaris-for-production.md     |  4 +--
 site/content/in-dev/unreleased/metastores.md  | 29 +++++++++++--------
 3 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/site/content/in-dev/unreleased/_index.md b/site/content/in-dev/unreleased/_index.md
index 8f233f2e4..19100e712 100644
--- a/site/content/in-dev/unreleased/_index.md
+++ b/site/content/in-dev/unreleased/_index.md
@@ -37,7 +37,7 @@ These pages refer to the current state of the main branch, which is still under
 Functionalities can be changed, removed or added without prior notice.
 {{< /alert >}}
 
-Checkout the [Quick Start]({{% ref "quickstart" %}}) page.
+Check out the [Quick Start]({{% ref "quickstart" %}}) page to get started.
 
 <!--
 Testing the `releaseVersion` shortcode here: version is: {{< releaseVersion >}}
diff --git a/site/content/in-dev/unreleased/configuring-polaris-for-production.md b/site/content/in-dev/unreleased/configuring-polaris-for-production.md
index 819d5ee8d..86ccd195e 100644
--- a/site/content/in-dev/unreleased/configuring-polaris-for-production.md
+++ b/site/content/in-dev/unreleased/configuring-polaris-for-production.md
@@ -59,7 +59,7 @@ Be sure to secure your metastore backend since it will be storing credentials an
 
 ### Configuring EclipseLink
 
-To use EclipseLink for metastore management, specify the configuration `metaStoreManager.conf-file` to point to an EclipseLink `persistence.xml` file. This file, local to the Polaris service, contains details of the database used for metastore management and the connection settings. For more information, refer to [metastore documentation]({{% ref "metastores" %}}) for details.
+To use EclipseLink for metastore management, specify the configuration `metaStoreManager.conf-file` to point to an EclipseLink `persistence.xml` file. This file, local to the Polaris service, contains details of the database used for metastore management and the connection settings. For more information, refer to the [metastore documentation]({{% ref "metastores" %}}).
 
 ### Bootstrapping
 
@@ -71,7 +71,7 @@ To bootstrap Polaris, run:
 java -jar /path/to/jar/polaris-service-all.jar bootstrap polaris-server.yml
 ```
 
-Afterwards, Polaris can be launched normally:
+Afterward, Polaris can be launched normally:
 
 ```bash
 java -jar /path/to/jar/polaris-service-all.jar server polaris-server.yml
diff --git a/site/content/in-dev/unreleased/metastores.md b/site/content/in-dev/unreleased/metastores.md
index 72d97a38b..220c1b72d 100644
--- a/site/content/in-dev/unreleased/metastores.md
+++ b/site/content/in-dev/unreleased/metastores.md
@@ -23,29 +23,31 @@ type: docs
 weight: 700
 ---
 
-This page documents the general configurations to connect to production database through [EclipseLink](https://eclipse.dev/eclipselink/).
+This page documents important configurations for connecting to production database through [EclipseLink](https://eclipse.dev/eclipselink/).
 
 ## Polaris Server Configuration
-Configure the `metaStoreManager` section in server configuration `polaris-server.yml` as follows:
+Configure the `metaStoreManager` section in the Polaris configuration (`polaris-server.yml` by default) as follows:
 ```
 metaStoreManager:
   type: eclipse-link
   conf-file: META-INF/persistence.xml
   persistence-unit: polaris
 ```
-`conf-file` points to the EclipseLink configuration file and `persistence-unit` tells which unit from the configuration file to use for database connection.
 
-E.g., `polaris-dev` and `polaris` persistence units are configured in `persistence.xml` to connect to development database and production database respectively. Updating `persistence-unit` from `polaris-dev` to `polaris` switch from the development to the production.
+`conf-file` must point to an [EclipseLink configuration file](https://eclipse.dev/eclipselink/documentation/2.5/solutions/testingjpa002.htm)
 
-`conf-file` by default points to the embedded resource file `META-INF/persistence.xml` in `polaris-eclipselink` module.
-To specify an external configuration file,
-1) Place `persistence.xml` into a jar file: `jar cvf /tmp/conf.jar persistence.xml`.
-2) Use `conf-file: /tmp/conf.jar!/persistence.xml`.
+By default, `conf-file` points to the embedded resource file `META-INF/persistence.xml` in the `polaris-eclipselink` module.
+
+In order to specify a configuration file outside the classpath, follow these steps.
+1) Place `persistence.xml` into a jar file: `jar cvf /tmp/conf.jar persistence.xml`
+2) Use `conf-file: /tmp/conf.jar!/persistence.xml`
 
 ## EclipseLink Configuration - persistence.xml
 The configuration file `persistence.xml` is used to set up the database connection properties, which can differ depending on the type of database and its configuration.
 
-Check out [default persistence.xml](https://github.com/apache/polaris/blob/main/extension/persistence/eclipselink/src/main/resources/META-INF/persistence.xml) for the complete sample and the following shows the database connection properties against file-based H2 database. Polaris creates and connects to a separate database for each realm. Specifically, `{realm}` placeholder in `jakarta.persistence.jdbc.url` is substituted with the actual realm name, allowing the Polaris server to connect to different databases based on the realm.
+Check out the default [persistence.xml](https://github.com/apache/polaris/blob/main/extension/persistence/eclipselink/src/main/resources/META-INF/persistence.xml) for a complete sample for connecting to the file-based H2 database. 
+
+Polaris creates and connects to a separate database for each realm. Specifically, the `{realm}` placeholder in `jakarta.persistence.jdbc.url` is substituted with the actual realm name, allowing the Polaris server to connect to different databases based on the realm.
 
 > Note: some database systems such as Postgres don't create databases automatically. Database admins need to create them manually before running Polaris server.
 ```xml
@@ -69,7 +71,9 @@ Check out [default persistence.xml](https://github.com/apache/polaris/blob/main/
 </persistence-unit>
 ```
 
-Build with H2 dependency and run Polaris service:
+A single `persistence.xml` can describe multiple [persistence units](https://eclipse.dev/eclipselink/documentation/2.6/concepts/app_dev001.htm). For example, with both a `polaris-dev` and `polaris` persistence unit defined, you could use a single `persistence.xml` to easily switch between development and production databases. Use `persistence-unit` in the Polaris server configuration to easily switch between persistence units.
+
+To build Polaris with the necessary H2 dependency and start the Polaris service, run the following:
 ```bash
 polaris> ./gradlew --no-daemon --info -PeclipseLink=true -PeclipseLinkDeps=com.h2database:h2:2.3.232 clean shadowJar
 polaris> java -jar  polaris-service/build/libs/polaris-service-*.jar server ./polaris-server.yml
@@ -77,7 +81,7 @@ polaris> java -jar  polaris-service/build/libs/polaris-service-*.jar server ./po
 
 ### Postgres
 
-The following shows a sample configuration for Postgres database.
+The following shows a sample configuration for integrating Polaris with Postgres.
 
 ```xml
 <persistence-unit name="polaris" transaction-type="RESOURCE_LOCAL">
@@ -100,7 +104,8 @@ The following shows a sample configuration for Postgres database.
   </properties>
 </persistence-unit>
 ```
-Build with Postgres dependency and run Polaris service:
+
+To build Polaris with the necessary Postgres dependency and start the Polaris service, run the following:
 ```bash
 polaris> ./gradlew --no-daemon --info -PeclipseLink=true -PeclipseLinkDeps=org.postgresql:postgresql:42.7.4 clean shadowJar
 polaris> java -jar  polaris-service/build/libs/polaris-service-*.jar server ./polaris-server.yml