intro page edits and link fixes

jyecusch · jyecusch · commit 217dce49fe44 · 2024-09-23T11:08:26.000+10:00
diff --git a/src/pages/index.mdx b/src/pages/index.mdx
@@ -14,18 +14,20 @@ export const disableEditGithub = true
 
 ---
 
-Nitric is a cloud framework with common resources like APIs, websockets, databases, queues, topics, buckets, and more.
+Nitric is a declarative cloud framework with common resources like APIs, websockets, databases, queues, topics, buckets, and more.
 
-However, Nitric is unique - it doesn't just deploy the resources, it helps you interact with them. It also makes them pluggable, so you can swap services or even whole clouds without changing your code.
+However, Nitric doesn't just deploy the resources, it helps you interact with them. It also makes them pluggable, so you can swap services or even whole clouds without changing your code.
 
 It's what's missing between applications and infrastructure automation.
 
 Oh, and it supports basically any language, like JavaScript, TypeScript, Python, Go, you name it.
 
 <div className="">
-<Libraries minimal />
+  <Libraries minimal />
 </div>
 
+If you're familiar Nitric already, you might want to jump to the [Installation](/getting-started/installation), [Guides](/guides) or [Resources](/apis) sections. Otherwise, keep reading to learn more about Nitric.
+
 ---
 
 ## Services
@@ -35,17 +37,17 @@ Services are the heart of Nitric apps, they're the entrypoints to your code. The
 ```yaml {{ label:"nitric.yaml" }}
 name: example
 services:
-    - match: services/*.ts
-      start: npm run dev:services $SERVICE_PATH
+  - match: services/*.ts
+    start: npm run dev:services $SERVICE_PATH
 ```
 
-You might have one service that handles everything, or a service for each route. It's up to you.
+You might have one service that handles everything, or a service for each route. It's up to you. Every matched services becomes a container, so you can scale them independently.
 
 ---
 
 ## Resources
 
-Resources are the building blocks of your apps. They're the databases, queues, buckets, etc. that your services interact with. If you want a resource, you just ask for it.
+Resources are the building blocks of your apps. They're the databases, queues, buckets, etc. that your services interact with. To request a resource, import the resource type and create one with a name.
 
 <CodeGroup>
 
@@ -94,21 +96,23 @@ void main() {
 
 </CodeGroup>
 
-Nitric collects everything your services request. When you deploy, the deployment plugin you choose creates the resources and services, then links it all together.
+Nitric collects everything your services request. When you deploy, the deployment plugin you choose creates the resources and services, then links them all together.
 
 <Note>
-  That probably sounds like magic, but it's more like a compiler for Infrastructure-as-Code - you can read about it in the [Concepts](/docs/concepts) section.
+  That might sound like magic, but it's more like a compiler for
+  Infrastructure-as-Code - you can read about it in the [Concepts](/concepts)
+  section.
 </Note>
 
 ---
 
-## Providers
+## Deployment Plugins (Providers)
 
-Nitric is designed to be independent of any platform, so you can run your apps anywhere. You can deploy to AWS, Azure, GCP, or even your own Kubernetes cluster. You can even deploy to multiple clouds at once.
+Nitric is designed to be independent of any platform, so you can run your apps anywhere. You can deploy to AWS, Azure, GCP, your own Kubernetes cluster or a single server. You could even deploy to multiple clouds at once.
 
-Seriously, is there really a difference between a bucket on AWS and a bucket on Azure? We don't think so. So why should the code be different?
+Are the differences between a bucket on AWS and a bucket on Azure important to most apps? We don't think so. So why should the code be different?
 
-Nitric abstracts away the differences, so you can focus on your app. The part that makes that possible is a plugin, we call a **Provider**.
+Nitric abstracts away API layer differences, so you can focus on your app. The part that makes that possible is a plugin, we call a **Provider**.
 
 <CodeGroup>
 
@@ -144,19 +148,19 @@ provider: custom/on-prem@1.0.0
 
 </CodeGroup>
 
-We have a few providers built-in with IaC from Pulumi or Terraform, but you can build your own with any tools you prefer and to anywhere you want.
+We have several providers built-in with IaC from [Pulumi](https://www.pulumi.com/) or [Terraform](https://www.terraform.io/), but you can build your own with any tools you prefer and **deploy anywhere**.
 
 ---
 
 ## Projects
 
-Projects built with Nitric don't have many restrictions. You can use most languages, most libraries, most tools, most clouds, most services, mostly anything you like. But, you need to have a `nitric.yaml` file in the root of your project.
+Projects built with Nitric don't have many restrictions. You can use most languages, libraries, tools, clouds, services, mostly anything you like. But, you need to have a `nitric.yaml` file in the root of your project.
 
 ```yaml {{ label:"nitric.yaml" }}
 name: example
 services:
-    - match: services/*.ts
-      start: npm run dev:services $SERVICE_PATH
+  - match: services/*.ts
+    start: npm run dev:services $SERVICE_PATH
 ```
 
 Nitric uses this to find your services, then it turns each service into a container, runs them in deployment mode to match the resources you requested and gives the result to the Provider - which either generates IaC (like Terraform) or automatically deploys your app.
@@ -229,6 +233,11 @@ curl -L "https://nitric.io/install?version=latest" | bash
 
 </InstallNitric>
 
+<Note>
+  Nitric has a few dependencies, like Docker, which you can read about in the
+  [Installation](/getting-started/installation) section.
+</Note>
+
 ### New
 
 You can create a new project from a template with the `new` command.
@@ -246,21 +255,28 @@ nitric start
 ```
 
 <Note>
-  Start also emulates the resources you requested, so you can test your app locally. And provides a Dashboard UI to interact with the resources.
+  Start also emulates the resources you requested, so you can test your app
+  locally. And provides a Dashboard UI to interact with the resources.
 </Note>
 
 ### Deploy
 
 You can deploy your project with the `up` command, once you have a stack file (deployment target).
 
 ```bash
+# Create a new stack (deployment target)
 nitric stack new
-
+# Deploy to the stack, using the provider in the stack file
 nitric up
 ```
 
 <Note>
-  Some providers don't deploy directly, instead they generate IaC files. In those cases you use the IaC tool to deploy (e.g. `terraform apply`).
+  Some providers deploy directly, others generate IaC files for existing tools
+  (like HCL for Terraform). In the cases where IaC is generated you use the
+  chosen IaC tool to deploy (e.g. `terraform apply`).
+
+Currently, all Pulumi providers deploy directly, while Terraform providers generate IaC.
+
 </Note>
 
 ### Tear Down
@@ -271,15 +287,20 @@ You can tear down your project with the `down` command.
 nitric down
 ```
 
+<Note>
+  If you used a provider that generates IaC, use the IaC tool to tear down (e.g.
+  `terraform destroy`).
+</Note>
+
 ---
 
 ## Local development
 
-Sometimes you just want to run your app locally and we let you do just that. And we don't mean "binds to a cloud environment and syncs your code, but doesn't work without Wifi" local, we mean "runs on your machine, on a desert island" local.
+Sometimes you'll want to run your app locally. We don't mean "binds to a cloud environment and syncs your code, but doesn't work without Wifi" local, we mean "runs on your machine, on a desert island" local.
 
 `nitric start` hosts entrypoints like APIs, websockets, and schedules, as well as resources like databases, topics, queues, key/value stores and buckets.
 
-It also provides a Dashboard to interact with your resources, so you can trigger schedules without waiting, or topics without a publisher, or upload test files to a bucket. It even produces a real-time architecture diagram of your services and resources.
+It also provides a Dashboard to interact with your resources, so you can trigger schedules without waiting, or topics without a publisher, or upload test files to a bucket. It even produces a live architecture diagram of your services and resources as your code updates.
 
 <img
   src="/docs/images/docs/dashboard-architecture.png"
@@ -293,36 +314,41 @@ It also provides a Dashboard to interact with your resources, so you can trigger
 
 The services of cloud providers are vast, we can't cover everything and we shouldn't. Many services are unique enough that abstraction would be a disservice. Nitric aims to make common "table stakes" services easy to use, but we never want to limit you.
 
+Here are some ways you can extend or escape Nitric.
+
 ### Runtime
 
 If you need to access a service in a way Nitric doesn't support, you can always use the provider's SDK directly. Code like this will always work:
 
 <CodeGroup>
 
 ```javascript
+// Import the AWS SDK
 import { S3Client } from '@aws-sdk/client-s3'
 
+// Use it like you normally would
 const s3 = new S3Client({ region: 'us-east-1' })
-
 const { Contents } = await s3.listObjectsV2({ Bucket: 'my-bucket' })
 ```
 
 ```python
+# Import the boto3 (AWS) SDK
 from boto3 import client
 
+# Use it like you normally would
 s3 = client('s3', region_name='us-east-1')
-
 response = s3.list_objects_v2(Bucket='my-bucket')
 ```
 
 ```go
 import (
   "context"
-
+  // Import the AWS SDK
   "github.com/aws/aws-sdk-go-v2/config"
   "github.com/aws/aws-sdk-go-v2/service/s3"
 )
 
+// Use it like you normally would
 cfg, _ := config.LoadDefaultConfig(context.TODO())
 client := s3.NewFromConfig(cfg)
 
@@ -332,12 +358,12 @@ output, _ := client.ListObjectsV2(context.TODO(), &s3.ListObjectsV2Input{
 ```
 
 ```dart
+// Import the AWS SDK
 import 'package:aws_s3/aws_s3.dart';
 
+// Use it like you normally would
 final s3 = S3(region: 'us-east-1');
-
 final response = await s3.listObjectsV2(Bucket: 'my-bucket');
-
 print(response.contents);
 ```
 
@@ -348,21 +374,22 @@ print(response.contents);
 If you need to change how Nitric deploys a resources or how it interacts with a service at runtime, you can [extend or modify a provider](/reference/providers/custom/extend-standard-provider).
 
 <Note>
-  For example, here's a [project that swaps SNS for EventBridge](https://github.com/jyecusch/iac-ifc-comparison) on AWS.
+  For example, here's a [project that swaps SNS for
+  EventBridge](https://github.com/jyecusch/iac-ifc-comparison) on AWS.
 </Note>
 
 ### Full Customization
 
-If you need to deploy to a cloud or new set of services that Nitric doesn't support, you can [build your own provider](/reference/providers/custom/building-custom-provider). This is a bit more advanced, but it's the ultimate escape hatch.
+If you need to deploy to a new platform or new set of services that Nitric doesn't support, you can [build your own provider](/reference/providers/custom/building-custom-provider). This is a bit more advanced, but it's the ultimate escape hatch.
 
 The included providers are written in Go and built using Terraform or Pulumi, but you can use any language or tool you like.
 
 ### Additional Resources
 
-If you need to use a service that Nitric doesn't support, you just do that like you always would. Nitric doesn't get in the way of you using the cloud, it just makes it easier.
+If you need to use a service/resource that Nitric doesn't support, you do that like you always would. Nitric doesn't get in the way of you using the cloud, it just makes it easier.
 
 ---
 
 ## What now?
 
-If you're still not sure what to make of Nitric, maybe start with the [Concepts](/docs/concepts) section, otherwise the best way to learn is to dive into the [Guides](/docs/guides) and start building your first project.
+If you're still not sure what to make of Nitric, maybe start with the [Concepts](/concepts) section, otherwise the best way to learn is to dive into the [Guides](/guides) and start building your first project.
