From 96e8ab919040945e98c14eab4336e85a0a7abc4d Mon Sep 17 00:00:00 2001
From: Betsy Gitelman <betsy.gitelman@enterprisedb.com>
Date: Fri, 4 Oct 2024 15:08:11 -0400
Subject: [PATCH] Edits to PostgreSQL on Windows dev env topic #6063

Edited all this doc while I was i there.
---
 advocacy_docs/dev-guides/deploy/docker.mdx    | 56 ++++++++--------
 advocacy_docs/dev-guides/deploy/windows.mdx   | 66 +++++++++----------
 advocacy_docs/dev-guides/index.mdx            |  4 +-
 .../working/psql-for-busy-developers.mdx      | 40 +++++------
 4 files changed, 81 insertions(+), 85 deletions(-)

diff --git a/advocacy_docs/dev-guides/deploy/docker.mdx b/advocacy_docs/dev-guides/deploy/docker.mdx
index b10ba81be4e..ecbff97efc1 100644
--- a/advocacy_docs/dev-guides/deploy/docker.mdx
+++ b/advocacy_docs/dev-guides/deploy/docker.mdx
@@ -5,20 +5,20 @@ description: Learn how to install PostgreSQL in a Docker container on your local
 deepToC: true
 ---
 
+Using Docker for your local PostgreSQL development environment streamlines setup, ensures consistency, and simplifies management. It provides a flexible, isolated, and portable solution that can adapt to various development needs and workflows.
+
 ## Prerequisites
 
 * Docker-compatible OS (macOS, Windows, Linux)
 
-Using Docker for your local PostgreSQL development environment streamlines setup, ensures consistency, and simplifies management. It provides a flexible, isolated, and portable solution that can adapt to various development needs and workflows.
-
 ## Preparing Docker
 
-### Install Docker: 
+### Install Docker
 
-Make sure Docker is installed on your machine or download and install it from [Docker’s official website](https://www.docker.com/products/docker-desktop/).
+Make sure Docker is installed on your machine, or download and install it from [Docker’s official website](https://www.docker.com/products/docker-desktop/).
 
 * macOS: Download and install Docker Desktop from Docker’s official website.  
-* Windows: Download and install Docker Desktop from Docker’s official website. Ensure WSL 2 is enabled if using Windows 10 or later.  
+* Windows: Download and install Docker Desktop from Docker’s official website. Ensure WSL 2 is enabled if using Windows 10 or later.
 * Linux: Install Docker using your distribution’s package manager. For example, on Ubuntu:  
 
 ```
@@ -31,9 +31,9 @@ newgrp docker
 ```
 
 
-### Pull the PostgreSQL Docker image:
+### Pull the PostgreSQL Docker image
 
-Open a terminal or command prompt and run the following command to pull the latest PostgreSQL image from Docker Hub:
+To pull the latest PostgreSQL image from Docker Hub, open a terminal or command prompt and run the following command:
 
 ```
 docker pull postgres
@@ -41,7 +41,7 @@ docker pull postgres
 
 ## Running the PostgreSQL container
 
-Run a new container with the PostgreSQL image using the following command:
+Run a new container with the PostgreSQL image:
 
 ```
 docker run --name my_postgres -d postgres -e POSTGRES_PASSWORD=mysecretpassword -v my_pgdata:/var/lib/postgresql/data -p 5432:5432
@@ -49,53 +49,53 @@ docker run --name my_postgres -d postgres -e POSTGRES_PASSWORD=mysecretpassword
 
 #### `--name my_postgres`
 
-The `--name` flag tells docker to creates a new container named `my_postgres`. 
+The `--name` flag tells Docker to create a new container named `my_postgres`. 
 
 #### `-d` 
 
-The `-d` flag tells Docker to run the container in detached mode. This means the container runs in the background and does not block the terminal.
+The `-d` flag tells Docker to run the container in detached mode. This means the container runs in the background and doesn't block the terminal.
 
 #### `postgres`
 
-This is the name of the image to run. Docker uses this name to pull the image from Docker Hub if it is not already present on the local machine.  Note that if we had not pulled it, this command would automatically pull the PostgreSQL image.
+This is the name of the image to run. Docker uses this name to pull the image from Docker Hub if it isn't already present on the local machine.  If you don't pull it, this command automatically pulls the PostgreSQL image.
 
 #### `-e POSTGRES_PASSWORD=mysecretpassword`
 
-The `-e` flag sets an environment variable `POSTGRES_PASSWORD` to `mysecretpassword`. This is used the password for the default `postgres` user. You should use a different password.
+The `-e` flag sets an environment variable `POSTGRES_PASSWORD` to `mysecretpassword`. This is the password for the default postgres user. We strongly recommend using a different password.
 
 #### `-v my_pgdata:/var/lib/postgresql/data`
-Docker uses volumes to persist data in Docker containers. This flag mounts a volume named `my_pgdata` to persist data. 
+Docker uses volumes to persist data in Docker containers. This flag mounts a volume named `my_pgdata` to persist data.
 The data in this case is whatever Postgres writes to the `/var/lib/postgresql/data` directory within the container. 
-These writes are persisted outside the container in a docker volume; the command `docker volume inspect my_pgdata` will show you information about that volume. 
+These writes are persisted outside the container in a Docker volume. The command `docker volume inspect my_pgdata` shows you information about that volume. 
 
 #### `-p 5432:5432`
 
-The `-p` flag maps the container’s port 5432 to the host machine’s port 5432. Port 5432 is Postgres's default port for communications. By using this flag, it allows you to access the PostgreSQL database from your host machine.
+The `-p` flag maps the container’s port 5432 to the host machine’s port 5432. Port 5432 is Postgres's default port for communications. Using this flag allows you to access the PostgreSQL database from your host machine.
 
 ## Verifying the container is running
 
-To verify that the container is running, use the following command:
+Verify that the container is running:
 
 ```
 docker ps
 ```
 
-This command lists all running containers. You should see the `my_postgres` container listed.
+This command lists all running containers, including the container you created (`my_postgres` in this example).
 
-You now have a persistent, locally accessible Postgres database running in a Docker container.
-You can now start using it.
+You now have a persistent, locally accessible Postgres database running in a Docker container and
+can start using it.
 
 ## Access PostgreSQL with a client
 
-To access the PostgreSQL database, without any additional tools, you can use the following command to open a PostgreSQL prompt:
+To access the PostgreSQL database without any additional tools, you can use the following command to open a PostgreSQL prompt:
 
 ```
 docker exec \-it my\_postgres psql \-U postgres
 ```
 
-This logs into the Docker container and runs the `psql` command as the `postgres` user from there.
+This command logs into the Docker container and runs the `psql` command as the postgres user from there.
 
-The `psql` command is a powerful tool for interacting with PostgreSQL databases. You should install it on your local machine to interact with the PostgreSQL database running in the Docker container.
+The `psql` command is a powerful tool for interacting with PostgreSQL databases. Install it on your local machine to interact with the PostgreSQL database running in the Docker container.
 
 ### macOS
 
@@ -151,31 +151,31 @@ postgresql://postgres:mysecretpassword@localhost:5432/postgres
       ('Jane', 'Smith', 'jane.smith@example.com', '2019-03-22');
    ```
 
-2. Stop and completely remove the container.  
+2. Stop and completely remove the container:
    ```
    docker stop my_postgres  
    docker rm my_postgres
    ```
 
-3. Recreate the container with the same volume.  
+3. Re-create the container with the same volume:
 
    ```
    docker run --name my_postgres -d postgres -e POSTGRES_PASSWORD=mysecretpassword -v my_pgdata:/var/lib/postgresql/data -p 5432:5432
    ```
 
-4. Verify Data Persistence.  
+4. Verify data persistence.  
    Access the PostgreSQL instance and check if the data still exists:  
      
    ```sql
    SELECT * FROM employees
    ```
 
-  If everything worked as expected, you should see the employee table with the data previously loaded still present.
+  If everything worked as expected, you'll see the employee table with the data previously loaded still present.
 
 
 ## Stopping and removing the container
 
-To stop and remove the container, use the following commands:
+To stop and remove the container:
 
 ```
 docker stop my_postgres  
@@ -184,7 +184,7 @@ docker rm my_postgres
 
 ## Deleting the volume
 
-To remove the volume containing the database, use the following command (after stopping and removing the container):
+To remove the volume containing the database, after stopping and removing the container, use the following command:
 
 ```
 docker volume rm my_pgdata
diff --git a/advocacy_docs/dev-guides/deploy/windows.mdx b/advocacy_docs/dev-guides/deploy/windows.mdx
index 7d9b70e02bf..d3c4fe449bc 100644
--- a/advocacy_docs/dev-guides/deploy/windows.mdx
+++ b/advocacy_docs/dev-guides/deploy/windows.mdx
@@ -6,14 +6,14 @@ product: postgresql
 iconName: logos/Windows
 ---
 
-## Prerequesites
+## Prerequisites
 
 - Windows 10 build 16299 or later
-- An account with Administrator rights
+- An account with administrator rights
 
 ## Installing
 
-For a development machine, we'll use [WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/) to download and install PostgreSQL:
+For a development machine, this example uses [WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/) to download and install PostgreSQL:
 
 ```
 winget install PostgreSQL.PostgreSQL.16
@@ -28,7 +28,9 @@ Starting package install...
 Successfully installed
 ```
 
-...where `16` is the major version of PostgreSQL we wish to install. This will install PostgreSQL in unattended mode (it won't ask you questions on what components to install, where to install them, or what the initial configuration should look like... Although you may be prompted by Windows to approve admin access for the installer). The installer will use the default location (`C:\Program Files\PostgreSQL\`) with the default password (`postgres`) and also install both [StackBuilder](/supported-open-source/postgresql/installing/using_stackbuilder/) and [pgAdmin](https://www.pgadmin.org/).
+Where `16` is the major version of PostgreSQL being installed. 
+
+This code installs PostgreSQL in unattended mode. (Unattended mode doesn't ask you questions about the components to install, where to install them, or what the initial configuration looks like. However, Windows might prompt you to approve admin access for the installer.) The installer uses the default location (`C:\Program Files\PostgreSQL\`) with the default password (`postgres`) and also installs both [StackBuilder](/supported-open-source/postgresql/installing/using_stackbuilder/) and [pgAdmin](https://www.pgadmin.org/).
 
 !!! Tip
 
@@ -49,38 +51,38 @@ PostgreSQL 16 PostgreSQL.PostgreSQL.16 16.4-1  winget
 PostgreSQL 9  PostgreSQL.PostgreSQL.9  9       winget
 ```
 
-Installers for release candidate versions of PostgreSQL are also available on EDB's website at https://www.enterprisedb.com/downloads/postgres-postgresql-downloads
+Installers for release candidate versions of PostgreSQL are also available on the [EDB website downloads page](https://www.enterprisedb.com/downloads/postgres-postgresql-downloads).
 
 !!!
 
 !!! SeeAlso "Further reading"
 
-For more control over installation (specifying components, location, port, superuser password...), you can also download and run the installer interactively by following the instructions in [Installing PostgreSQL on Windows](https://www.enterprisedb.com/docs/supported-open-source/postgresql/installing/windows/). 
+For more control over installation (specifying components, location, port, superuser password, and so on), you can also download and run the installer interactively by following the instructions in [Installing PostgreSQL on Windows](https://www.enterprisedb.com/docs/supported-open-source/postgresql/installing/windows/).
 
 !!!
 
 ## Add PostgreSQL commands to your path
 
-PostgreSQL comes with [several useful command-line tools](https://www.postgresql.org/docs/current/reference-client.html) for working with your databases. For convenience, you'll probably want to add their location to your path.
+PostgreSQL comes with [several useful command-line tools](https://www.postgresql.org/docs/current/reference-client.html) for working with your databases. For convenience, you can add their location to your path.
 
-1.  Open the System Properties control panel and select the Advanced tab (or run `SystemPropertiesAdvanced.exe`)
-2.  Activate the "Environment Variables..." button to open the envornment variables editor
-3.  Find the `Path` variable under the "System variables" heading, and click "Edit..."
-4.  Add the path to the bin directory of the PostgreSQL version you installed, e.g.  `C:\Program Files\postgresql\16\bin\` (where *16* is the version of PostgreSQL that you installed).
+1.  Open the System Properties control panel and select the **Advanced** tab, or run `SystemPropertiesAdvanced.exe`.
+2.  Select **Environment Variables** to open the environment variables editor.
+3.  Find the `Path` variable under the **System variables** heading, and select **Edit**.
+4.  Add the path to the bin directory of the PostgreSQL version you installed, for example, `C:\Program Files\postgresql\16\bin\`, where `16` is the version of PostgreSQL that you installed.
 
-!!! Info "This only affects new command prompts"
+!!! Info "This affects only new command prompts"
 
-If you have a command prompt open already, you'll need to close and reopen in order for your changes to the system path to take effect.
+If you have a command prompt open, close and reopen it to make your changes to the system path take effect.
 
 !!!
 
 ## Verifying your installation
 
-If the steps above completed successfully, you'll now have a PostgreSQL service running with the default database and superuser account. Let's verify this by connecting, creating a new user and database, and then connecting using that user.
+After installing PostgreSQL and adding the commands to your path, a PostgreSQL service will be running with the default database and superuser account. You can verify this by connecting, creating a new user and database, and then connecting using that user.
 
 ### Connect with psql
 
-Open a new command prompt, and run
+Open a new command prompt, and run:
 
 ```
 psql -U postgres
@@ -100,11 +102,11 @@ When prompted, enter the default password (`postgres`).
 
 !!! Warning
 
-We're setting up an environment for local development, and have no intention of enabling remote connections or working with sensitive data - so leaving the default password is fine. Never leave the default password set on a production or multi-user system!
+Because you're setting up an environment for local development and don't intend to enable remote connections or work with sensitive data, leaving the default password is fine. Never leave the default password set on a production or multi-user system.
 
 !!!
 
-It's a good practice to develop with a user and database other than the default (`postgres` database and `postgres` superuser) - this allows us to apply the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) and helps avoid issues later on when you go to deploy: since the superuser is allowed to modify *anything*, you'll never encounter permissions errors even if your app's configuration has you reading or writing to the wrong table, schema or database... Yet that's certainly not the sort of bug you'd wish to ship! So let's start off right by creating an app user and giving it its own database to operate on:
+It's good practice to develop with a user and database other than the default (`postgres` database and postgres superuser). Doing so allows you to apply the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) and helps to avoid issues when you deploy. Since the superuser can modify everything, if you develop as superuser you'll never encounter permissions errors even if your app's configuration has you reading or writing to the wrong table, schema, or database. That's a bug you don't want to ship! Start off right by creating an app user and giving it its own database to operate on:
 
 ```
 create user myapp with password 'app-password';
@@ -121,7 +123,7 @@ CREATE DATABASE
 
 !!!
 
-Now let's quit psql and connect with pgAdmin as our new user. Run,
+Now. quit psql and connect with pgAdmin as the new user:
 
 ```
 \q
@@ -129,35 +131,33 @@ Now let's quit psql and connect with pgAdmin as our new user. Run,
 
 ### Connect with pgAdmin
 
-Launch pgAdmin via the Start menu (you can find it under "PostgreSQL 16", or just type "pgAdmin").
+Launch pgAdmin using the Start menu. You can find it under **PostgreSQL 16**, or just type `pgAdmin`.
 
 ![pgAdmin 4 default view - server groups on left, welcome message on right](images/pgadmin-default.png)
 
-If you poke around a bit (by expanding the Servers group on the left), you'll see that pgAdmin comes with a default connection configured for the `postgres` user to the `postgres` database in our local PostgreSQL server.
+If you poke around a bit (by expanding the Servers group on the left), you'll see that pgAdmin comes with a default connection configured for the postgres user to the `postgres` database in the local PostgreSQL server.
 
-Let's add a new connection for our app user to our app database.
+Add a connection for the app user to the app database.
 
-1. Right-click the Servers entry on the left, select Register and click Server:
+1. Right-click the Servers entry on the left, and select **Register > Server**.
 
   ![pgadmin Servers group menu with register item and server submenu item selected](images/pgadmin-register-server.png)
 
-2. On the General tab, give it a descriptive name like "myapp db"
-
-3. Switch to the Connection tab:
+2. On the **General** tab, give the server a descriptive name, like `myapp db`.
 
-   enter connection information, using the new role and database we created in psql above:
+3. On the **Connection** tab, enter connection information, using the new role and database you created in psql earlier:
    
-   - `localhost` for Host name/address
-   - `appdb` for Maintenance database
-   - `myapp` for Username
-   - `app-password` for Password
+   - `localhost` for **Host name/address**
+   - `appdb` for **Maintenance database**
+   - `myapp` for **Username**
+   - `app-password` for **Password**
   
-  ...and check the *Save password?* option and click the Save button.
+  Select the **Save password?** option and select **Save**.
 
     ![pgadmin screen showing two server connections configured under Servers group on left, with PostgreSQL 16 disconnected and myapp db connected and selected, with activity charts for myapp db shown on right](images/pgadmin-connected.png)
 
-Note that some areas that require system-level permissions (e.g., logs) are unavailable, as you're not connected as a superuser. For these, you can use the default superuser connection.
+Because you're not connected as a superuser, some areas that require system-level permissions, such as logs, are unavailable. For these, you can use the default superuser connection.
 
 ## Conclusion
 
-By following these steps, you've created a local environment for developing against PostgreSQL. You've created your own database and limited-access user to own it, and can proceed to create a schema, connect application frameworks, run tests, etc.
+By following these steps, you've created a local environment for developing against PostgreSQL. You've created your own database and limited-access user to own it and can proceed to create a schema, connect application frameworks, run tests, and so on.
diff --git a/advocacy_docs/dev-guides/index.mdx b/advocacy_docs/dev-guides/index.mdx
index 39d2f501184..3b43ad92495 100644
--- a/advocacy_docs/dev-guides/index.mdx
+++ b/advocacy_docs/dev-guides/index.mdx
@@ -14,9 +14,9 @@ navigation:
 
 The EDB Postgres AI Developer Guides are all about providing you, the developer, with the information you need to accelerate your development efforts using the EDB Postgres AI platform. The guides cover a wide range of topics, from setting up your development environment to deploying Postgres and AI applications.
 
-## Deploying Postgres Locally for developers
+## Deploying Postgres locally for developers
 
-* [Deploying Postgres Using Docker Locally](deploy/docker)
+* [Deploying Postgres using Docker locally](deploy/docker)
 
 * [Deploying PostgreSQL for development and testing on Microsoft Windows](deploy/windows)
 
diff --git a/advocacy_docs/dev-guides/working/psql-for-busy-developers.mdx b/advocacy_docs/dev-guides/working/psql-for-busy-developers.mdx
index ff2f0f0a827..1468e8e0f72 100644
--- a/advocacy_docs/dev-guides/working/psql-for-busy-developers.mdx
+++ b/advocacy_docs/dev-guides/working/psql-for-busy-developers.mdx
@@ -1,14 +1,14 @@
 ---
 title: PSQL for busy developers
 navTitle: PSQL for developers
-description: How to use PSQL for common developer tasks
+description: How to use PSQL for common developer tasks.
 ---
 
 The PSQL command line tool is essential in a developer's toolkit as it provides full command-line access to PostgreSQL databases. 
 
 ## Getting psql installed
 
-The `psql` command is a powerful tool for interacting with PostgreSQL databases. You should install it on your local machine to interact with the PostgreSQL database. Unless you've just installed Postgres natively on your machine, you'll need to install the `psql` client. 
+The `psql` command is a powerful tool for interacting with PostgreSQL databases. Install psql on your local machine to interact with the PostgreSQL database. Unless you've just installed Postgres natively on your machine, you'll need to install the psql client. 
 
 ### macOS:
 
@@ -42,42 +42,38 @@ Always wrap your connection string in single quotes to avoid the shell interpret
 
 ### PGPASSWORD environment variable
 
-Best practice is to not have your password in your connection string or in your command history. Instead, you can use the `PGPASSWORD` environment variable to store your Postgres password. This is simple, but not very secure because some Unix systems allow other users to see the environment variables of other users.
+Best practice is not to have your password in your connection string or in your command history. Instead, you can use the `PGPASSWORD` environment variable to store your Postgres password. This is simple but not very secure because some Unix systems allow other users to see the environment variables of other users.
 
 ### .pgpass file
 
-Creating a .pgpass file is a more secure way to store your password. The .pgpass file is a plain text file that contains the connection information for your databases. The file should be stored in your home directory and should be readable only by you. The file should have the following format:
+Creating a `.pgpass` file is a more secure way to store your password. The `.pgpass` file is a plain text file that contains the connection information for your databases. Store the file in your home directory and make it readable only by you. Usee the following format:
 
 ```
 hostname:port:database:username:password
 ```
 
-Hostname, port, database and username can all be set to wildcards to match any value. For example, `*:*:*:postgres:password` would match any database on any host for the user `postgres`.
+Hostname, port, database, and username can all be set to wildcards to match any value. For example, `*:*:*:postgres:password` matches any database on any host for the user postgres.
 
-Read more about the .pgpass file in the [Postgres documentation](https://www.postgresql.org/docs/current/libpq-pgpass.html).
+Read more about the `.pgpass` file in the [Postgres documentation](https://www.postgresql.org/docs/current/libpq-pgpass.html).
 
-## The PSQL command line
+## The psql command line
 
-You can enter SQL commands directly into the PSQL command line. Be sure to end each command with a semicolon, otherwise PSQL doesn't execute the command. 
+You can enter SQL commands directly into the psql command line. Be sure to end each command with a semicolon, otherwise psql doesn't execute the command.
 
-You can use tab-completion in many situations to help you complete commands and table names. Pressing tab at the start of a line will show you a list of available SQL commands.
+You can use tab completion in many situations to help you complete commands and table names. Press **Tab** at the start of a line to display a list of available SQL commands.
 
-PSQL also has a number of built-in commands that can help you manage your databases and tables.
+The psql tool also has built-in commands that can help you manage your databases and tables.
 
 
 | Command         | Description                                              |
 |-----------------|----------------------------------------------------------|
-| `\l`            | List all databases                                       |
-| `\c`            | Connect to a database                                    |
-| `\d`            | List tables, sequences and views in the current database |
-| `\d table_name` | Describe a table                                         |
-| `\watch seconds` | Re-run a query every `seconds`                          |
-| `\q`            | Quit PSQL                                                |
-
-`\d` is a very useful command that shows a range of different information when followed by another character. Think of it as `d` for display. For example, `\dt` shows all the tables in the current database, `\dv` shows all the views, and `\ds` shows all the sequences.
-
-`\watch` is useful when you want to repeat running a query at regular intervals. For example, you could use `\watch 5` to run a query every 5 seconds. The query that will be re-run is the last query you entered.
-
-
+| `\l`            | List all databases.                                       |
+| `\c`            | Connect to a database.                                    |
+| `\d`            | List tables, sequences, and views in the current database. |
+| `\d <table_name>` | Describe a table.                                         |
+| `\watch <seconds>` | Rerun a query every `<seconds>` seconds.                          |
+| `\q`            | Quit PSQL.                                                |
 
+`\d` is a useful command that shows a range of different information when followed by another character. Think of it as `d` for display. For example, `\dt` shows all the tables in the current database, `\dv` shows all the views, and `\ds` shows all the sequences.
 
+`\watch` is useful when you want to repeat running a query at regular intervals. For example, you can use `\watch 5` to run a query every 5 seconds. The query that's rerun is the last query you entered.