Apply suggestions from code review

Author: treysp

docs/cloud/features/security/security.md

@@ -12,8 +12,8 @@ Below is a diagram of the components along with their descriptions.
 ![tobiko_cloud_standard_deployment](./tcloud_standard_deployment.png){ width=80% height=60% style="display: block; margin: 0 auto" }
 
 - **Scheduler**: Orchestrates schedule cadence and hosts state metadata (code versions, logs, cost)
-- **Executor**: Applies code changes and runs SQL queries (actual data processing in SQL Engine) and python models in proper DAG order.
-- **Gateway**: Stores authentication to SQL Engine. Secured through encryption.
+- **Executor**: Applies code changes and runs SQL queries (actual data processing in SQL Engine) and Python models in proper DAG order.
+- **Gateway**: Stores authentication credentials for SQL Engine. Secured through encryption.
 - **SQL Engine**: Processes and stores data based on the above instructions within the **customer’s** environment.
 
 ## Tobiko Cloud Hybrid Deployment
@@ -28,27 +28,27 @@ Below is a diagram of the components along with their description.
 
 ![tobiko_cloud_hybrid_deployment](./tcloud_hybrid_deployment.png){ width=80% height=60% style="display: block; margin: 0 auto" }
 
-- **Scheduler**: Orchestrates schedule cadence and hosts state metadata(code versions, logs, cost). Never **pushes** instructions to executor.
-- **Executor**: Appplies code changes and runs SQL queries and python models in proper DAG order (actual data processing in SQL Engine)
-- **Gateway**: Stores authentication to SQL Engine. Secured through your secrets manager or Kubernetes Secrets.
+- **Scheduler**: Orchestrates schedule cadence and hosts state metadata (code versions, logs, cost). **Never pushes** instructions to executor.
+- **Executor**: Appplies code changes and runs SQL queries and Python models in proper DAG order (actual data processing in SQL Engine)
+- **Gateway**: Stores authentication credentials for SQL Engine. Secured through your secrets manager or Kubernetes Secrets.
 - **SQL Engine**: Processes and stores data based on the above instructions
-- **Executor -> Scheduler**: This is a pull-only mechanism as stated abvoe. 
+- **Executor -> Scheduler**: A pull-only mechanism for obtaining work tasks. 
 - **Helm Chart**: For production environements, we provide a [Helm chart](../scheduler/hybrid_executors_helm.md) that includes robust configurability, secret management, and scaling options.
-- **Docker Compose**: For simpler environments or testing, we offer a [Docker Compose setup](../scheduler/hybrid_executors_docker_compose) to quickly deploy executors on any machine with Docker.
+- **Docker Compose**: For simpler environments or testing, we offer a [Docker Compose setup](../scheduler/hybrid_executors_docker_compose.md) to quickly deploy executors on any machine with Docker.
 
 
 
 ## Internal Code Practices
 
-Our coding standards are guidelines we enforce throughout the organization to write, maintain, and collaborate on code effectively. These practice ensure consistency, maintainability, reliability, and most importantly, trust. 
+We enforce coding standards throughout Tobiko to write, maintain, and collaborate on code effectively. These practice ensure consistency, maintainability, reliability, and most importantly, trust. 
 
-Below you will find a few examples of our internal code requirements. 
+A few key components of our internal code requirements:
 
-- We used signed commits, required approvers, and signed Docker artifacts.
-- Each commit to main must be approved by someone other than the author.
-- We follow the standard of signing commits and registering the key with GitHub. [Github Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
-- Binary is signed using cosign and OIDC for keyless. [Signing docs](https://docs.sigstore.dev/cosign/signing/overview/)
-- Attestations are created to certify an image. We use GCP Binary Authorization to enforce this. [Attestation docs](https://cloud.google.com/binary-authorization/docs/key-concepts#attestations)
+- We used signed Git commits, required approvers, and signed Docker artifacts.
+- Each commit to a `main` branch must be approved by someone other than the author.
+- We sign commits and register the key with GitHub ([Github Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits))
+- Binaries are signed using cosign and OIDC for keyless ([Signing docs](https://docs.sigstore.dev/cosign/signing/overview/)
+- Attestations are created to certify an image, enforced with GCP Binary Authorization ([Attestation docs](https://cloud.google.com/binary-authorization/docs/key-concepts#attestations))
 - Encryption is a key feature of our security posture and is enforced at each stage of access. For example, the state database automatically encrypts all data. Credentials are also securely encrypted and stored. 
 - We back up each state database nightly and before upgrades. These backups are stored for 14 days.
 
@@ -61,11 +61,13 @@ At least once a year, Tobiko engages a third-party security firm to perform a pe
 
 ### How do we protect PGP keys?
 
-If an employee loses their laptop, we don't need to get the old PGP key back. We use GitHub to sign code. At the time the code was committed, the PGP key was valid. When an employee loses their laptop, we will invalidate it, and they will regenerate a new key. The old commits are valid because the PGP key was valid at the time.
+If an employee loses their laptop, we don't need to get the old PGP key back because we can invalidate the key directly. 
+
+We use GitHub to sign code commits. At the time the code was committed, the PGP key was valid. When an employee loses their laptop, we will invalidate it, and they will regenerate a new key to use in future commits. The old commits are still valid because the PGP key was valid at the time the commit was made.
 
 ### How do we invalidate PGP keys if someone did steal it and could potentially use it?
 
-Revoke access for the GitHub user account associated with the compromised key and not give them access again until the old PGP key is deprecated and issue a new PGP key.
+Revoke access for the GitHub user account associated with the compromised key and not give them access again until the old PGP key is deprecated and a new key issued.
 
 ### If someone steals a laptop, what's our continuity plan in protecting code?