More docs fixes

docs/concepts/accounts.md

@@ -6,32 +6,26 @@ sidebar_position: 100
 
 # Accounts
 
-In this section, we'll be talking about a couple different topics related to accounts in Defang. First we'll cover authentication and how to create an account, and then we'll talk about how resources are organized within a cloud environment using your account info.
+Below, we will cover account creation with Defang, and how resources are organized within a cloud environment using your account info.
 
-:::tip Why do I need an account?
-Defang requires an account so we can organize your resources and provide you with a way to manage them. We also use your account to authenticate you when you interact with [Defang Playground](./defang-playground.md) and the [Defang Portal](./portal.md).
-
-Eventually, billing and payment information will be associated with your account.
-:::
+Defang requires an account so we can organize your resources and provide you with a way to manage them. We also use your account to authenticate you when you interact with [Defang Playground](./defang-playground.md) and the [Defang Portal](./portal.md). Billing and payment information is also associated with your account.
 
 ## Creating an Account
 
-To create an account, login to Defang and accept the [terms of service](https://defang.io/terms-service.html) using the [CLI](/docs/concepts/authentication.md).
+To create an account, log in to Defang and accept the [Terms of Service](https://defang.io/policies/terms-service/) using the [CLI](/docs/concepts/authentication.md).
+
+At the moment, the only way to authenticate with Defang is through GitHub. We plan to offer other [authentication](/docs/concepts/authentication.md) providers in the future. 
 
-At the moment, the only way to authenticate with Defang is through GitHub. We plan to offer other authentication providers in the future.
+:::tip
+Keep in mind that your Defang account is separate from your [cloud provider account](./defang-byoc.md). You will need to authenticate with your cloud provider account separately to deploy services to your own cloud account.
+:::
 
 ## Structure
 
-Your GitHub username will be used as your Defang username and your Defang username is used to group all your services and to generate domains for your services with the following structure:
+Your GitHub username will be used as your Defang username. Your Defang username is used to group all your [services](/docs/concepts/services) and generate domains for your services with the following structure:
 
 ```
 <username>-<servicename>--<port>.prod1.defang.dev
 ```
 
-:::warning
-Keep in mind that your Defang account is separate from your [cloud provider account](./defang-byoc.md). You will need to authenticate with your cloud provider account separately to deploy services to your own cloud account.
-:::
-
-:::info
-We plan to introduce a more robust system for managing accounts, permissions, service groups, etc. in the future.
-:::
+For more about domain structures, see our [Domains](/docs/concepts/domains#structure) page.

docs/concepts/authentication.md

@@ -6,14 +6,14 @@ description: Authenticating with Defang.
 
 # Authentication
 
-To do pretty much anything with Defang, you'll need to authenticate with the system. You can do this by running the following command:
+To do pretty much anything with Defang, you'll need to authenticate with the system. You can do this by running the following command in the [CLI](/docs/getting-started):
 
 ```bash
 defang login
 ```
 
-This will prompt you to open a browser and log into your Defang account. For now, the only way to login is with GitHub, though we will offer other providers to authenticate in the future. Once you've logged in, you can close the browser and return to the terminal. You should see a message that you've successfully logged in.
+This will prompt you to open a browser and log in to your [Defang account](/docs/concepts/accounts). For now, the only way to log in is with GitHub, though we will offer other providers to authenticate in the future. Once you've logged in, you can close the browser and return to the terminal. You should see a message that you've successfully logged in.
 
-:::warning
+:::tip
 Keep in mind that your Defang account is separate from your [cloud provider account](/docs/concepts/defang-byoc). You will need to authenticate with your cloud provider account separately to deploy services to your own cloud account.
 :::

docs/concepts/deployments.md

@@ -10,12 +10,22 @@ When you deploy using Defang, whether it's with `defang compose up` with a [Comp
 
 ## Deploying Updates
 
-When you run a deployment to update one or more services, Defang will also make sure to get your new services up and running before deprovisioning any old services so you don't have to worry about downtime.
+When you run a deployment to update one or more [services](/docs/concepts/services), Defang will build new images for your services, and provision new resources to replace your existing services.
+
+### Zero Downtime Deployments
+
+Defang can deploy your services using different [modes](/docs/concepts/deployment-modes). When using the `production` mode, Defang will make sure the new replacement services are healthy before deprovisioning your existing services.
+
+By default, using the `development` mode, Defang will deprovision your existing services before provisioning replacements. This helps reduce costs.
 
 :::info
-In [Defang BYOC](./defang-byoc.md), Defang will use your cloud provider account to build and store your images. In [Defang Playground](./defang-playground.md) we will build and store your images for you.
+In [Defang BYOC](./defang-byoc.md), Defang uses your cloud provider account to build and store your images. In [Defang Playground](./defang-playground.md), we build and store your images for you.
 :::
 
+
+### Deployment Modes
+
+As mentioned above, Defang offers different [deployment modes](/docs/concepts/deployment-modes): `development`, `staging`, and `production`. You can switch the modes using the `--mode` CLI flag.
 :::warning
 Workloads with GPUs do not support zero downtime deployments. If you have a workload with a GPU, you will experience downtime during updates.
 :::
@@ -26,4 +36,4 @@ Defang defaults to "spot" instances. This is a cost-effective way to run your wo
 
 :::info
 In the future, we may provide a way to use "on-demand" instances for workloads that require more stability.
-:::
+:::

docs/concepts/domains.mdx

@@ -30,7 +30,7 @@ https://<username>-<service-name>--<port>.defang.dev
 If you're using [Defang BYOC](./defang-byoc.md), your domain will be:
 
 ```
-https://<service-name>--<port>.username.defang.app
+https://<service-name>--<port>.<username>.defang.app
 ```
   </TabItem>
 </Tabs>
@@ -114,4 +114,3 @@ As of now, the Pulumi provider does not support [Defang BYOC](./defang-byoc.md)
 :::
   </TabItem>
 </Tabs>
-

docs/concepts/managed-storage/managed-postgres.md

@@ -6,7 +6,7 @@ sidebar_position: 1000
 
 # Managed Postgres
 
-Postgres, or PostgreSQL, is an advanced open-source relational database system known for its robustness, extensibility, and compliance with SQL standards, making it a popular choice for complex applications requiring reliable data integrity and sophisticated querying capabilities.
+Postgres, or PostgreSQL, is a powerful open-source relational database system known for its robustness, extensibility, and compliance with SQL standards, making it ideal for complex applications requiring reliable data integrity and advanced querying. Defang can help you provision a managed Postgres instance.
 
 ## Current Support
 
@@ -75,13 +75,13 @@ For a smoother experience with Defang, we recommend using Postgres 14 for your c
 
 ## Final Snapshots
 
-When a project is deployed to a production environment any managed postgres instances are automatically configured to create a snapshot of the database before deletion. The snapshot will be named with the following format
+When a project is deployed to a [production environment](/docs/concepts/deployment-modes), any managed Postgres instances are automatically configured to create a snapshot of the database before deletion. The snapshot will be named with the following format:
 
 `
 <project-name>-<service>-postgres-<id>-final-snapshot
 `
 
-The AWS Console can be used to restore a snapshop into a new instance of postgres.
+The AWS Console can be used to restore a snapshot into a new instance of Postgres.
 
 <!-- 
 ### Major Version Updating of Engine

docs/concepts/managed-storage/managed-redis.md

@@ -33,11 +33,11 @@ cache:
 
 ## Final Snapshots
 
-When a project is deployed with the `production` [deployment mode](/docs/concepts/deployment-modes) any managed redis instances are automatically
-configured to create a snapshot of the datastore before deletion. The snapshot will be named with the following format
+When a project is deployed with the `production` [deployment mode](/docs/concepts/deployment-modes), any managed Redis instances are automatically
+configured to create a snapshot of the datastore before deletion. The snapshot will be named with the following format:
 
 `
 <project-name>-<service>-redis-<id>-final-snapshot
 `
 
-The AWS Console can be used to restore a snapshop into a new instance of redis.
+The AWS Console can be used to restore a snapshot into a new instance of Redis.

docs/concepts/networking.mdx

@@ -11,7 +11,7 @@ import TabItem from '@theme/TabItem';
 Defang configures Security Groups, deploys applications to a private subnet and uses an Application Load Balancer to route traffic to your services from the public internet only when required.
 
 :::tip
-This page is about internal networking only. If you want to configure your services to be accessible from the public internet, check the [domains page](./domains.mdx).
+This page is about internal networking only. If you want to configure your services to be accessible from the public internet, check the [Domains page](./domains.mdx).
 :::
 
 ## Internal Communication
@@ -65,4 +65,4 @@ Internal communication between services in Defang BYOC follows the following pat
 http://<service-name>:<port>
 ```
   </TabItem>
-</Tabs>
+</Tabs>

docs/concepts/observability.md

@@ -1,17 +1,21 @@
 ---
 title: Observability
-description: Monitor and debug your Defang services with the Defang CLI and portal.
+description: Monitor and debug your Defang services with the Defang CLI and Portal.
 sidebar_position: 600
 ---
 
 # Observability
 
-You can easily monitor and debug your Defang services at build and runtime using the Defang CLI and portal.
+You can easily monitor and debug your Defang services at build and runtime using the Defang CLI and Portal.
 
-When you deploy a service using the `defang compose up`, the CLI will automatically start tailing the build and runtime logs for your service. You can also view the logs for your service in the portal, or by using the `defang tail` command.
+When you deploy a service using the `defang compose up`, the CLI will automatically start tailing the build and runtime logs for your service. You can also view the logs for your service in the Portal, or by using the `defang tail` command.
+
+:::tip
+Defang has a tutorial on how you can [monitor your services' status and logs](/docs/tutorials/monitoring-your-services). 
+:::
 
 :::warning
-Keep in mind that the Defang Portal only displays services deployed to Defang Playground.
+Keep in mind that the [Defang Portal](./portal.md) only displays services deployed to Defang Playground.
 :::
 
 ## Tail
@@ -25,4 +29,4 @@ defang tail --etag ua119053ehi2
 
 ## Architecture
 
-In [BYOC](./defang-byoc.md), output is logged to the native logging tools within your cloud provider. The CLI then tails the output as needed.
+In [Defang BYOC](./defang-byoc.md), output is logged to the native logging tools within your cloud provider. The CLI then tails the output as needed.

docs/concepts/portal.md

@@ -8,14 +8,13 @@ sidebar_position: 700
 
 You can log into the Defang Portal at [portal.defang.dev](https://portal.defang.dev) using your [Defang account](./accounts.md) to view the state of your Defang services running in the Defang Playground for non-production applications.
 
-You can use the Portal to get an overview of your services, view the logs for each service, quickly access exposed ports, view environment variables, and more.
-
+You can use the Portal to get an overview of your [services](/docs/concepts/services), view the logs for each service, quickly access exposed ports, view environment variables, and more.
 
 :::info
-The Defang Portal displays services deployed to Playground. 
+The Defang Portal displays services deployed to Defang Playground. 
 To view services deployed to Defang BYOC, please check out [Monitoring Your Services](/docs/tutorials/monitoring-your-services).
 :::
 
 :::tip
-We have a tool in place to help [debug](/docs/concepts/debug) your application in production. 
-:::
+Need help with a failing deployment? Defang provides a tool to help [debug](/docs/concepts/debug) in your application.
+:::

docs/concepts/services.md

@@ -10,14 +10,14 @@ Defang allows you deploy services defined as containers. You can define your ser
 
 `<username>-<service-name>`
 
-You can learn more about accounts and usernames in the [accounts page](./accounts.md).
+You can learn more about accounts and usernames in the [Accounts page](./accounts.md).
 
-:::tip Service Names
+:::tip
 Service names are defined in your Compose file or your Pulumi program.
 :::
 
-You can learn more about about how to define [services with Compose files here](./compose.md) and [services with Pulumi here](./pulumi.md). You can learn more about how services are deployed in the [deployment page](./deployments.md).
+Defang manages the deployment process for services. You can learn more about how services are deployed in the [Deployment page](./deployments.md).
 
 :::info
-While this is the current state of the Defang model, we plan to add support for other types of services in the future, including serverless functions.
+We plan to add support for other types of services in the future, including serverless functions.
 :::

docs/tutorials/monitoring-your-services.md

@@ -47,6 +47,6 @@ $ defang logs --type=build
 All of the above flags can be combined to get the exact logs you need. See the CLI reference for [`defang tail`](/docs/cli/defang_tail) for more information.
 
 :::info
-* To learn more about observability in Defang, check out the [observability page](../concepts/observability.md).
+* To learn more about observability in Defang, check out the [Observability page](../concepts/observability.md).
 * Note that the Defang Portal only displays services deployed to Defang Playground.
 :::