Queuing docs simplified, partial written

Author: matt-aitken

docs/mint.json

@@ -485,11 +485,7 @@
             "v3/wait-for-request"
           ]
         },
-        "v3/environment-variables",
-        {
-          "group": "Queues",
-          "pages": ["v3/concurrency", "v3/one-at-a-time", "v3/parallelism", "v3/per-tenant"]
-        },
+        "v3/queue-concurrency",
         {
           "group": "Testing",
           "pages": ["v3/run-tests", "v3/automated-tests"]

docs/v3/concurrency.mdx

@@ -0,0 +1,81 @@
+---
+title: "Concurrency & Queues"
+description: "Configure what you want to happen when there is more than one run at a time."
+---
+
+Controlling concurrency is useful when you have a task that can't be run concurrently, or when you want to limit the number of runs to avoid overloading a resource.
+
+## One at a time
+
+This task will only ever have a single run executing at a time. All other runs will be queued until the current run is complete.
+
+```ts /trigger/one-at-a-time.ts
+export const oneAtATime = task({
+  id: "one-at-a-time",
+  queue: {
+    concurrencyLimit: 1,
+  },
+  run: async ({ payload, ctx }) => {
+    //...
+  },
+});
+```
+
+## Parallelism
+
+You can execute lots of tasks at once by combining high concurrency with [batch triggering](/v3/triggering) (or just triggering in a loop).
+
+```ts /trigger/parallelism.ts
+export const parallelism = task({
+  id: "parallelism",
+  queue: {
+    concurrencyLimit: 100,
+  },
+  run: async ({ payload, ctx }) => {
+    //...
+  },
+});
+```
+
+<Warning>
+  Be careful with high concurrency. If you're doing API requests you might hit rate limits. If
+  you're hitting your database you might overload it.
+</Warning>
+
+<Note>
+  Your organization has a maximum concurrency limit which depends on your plan. If you're a paying
+  customer you can request a higher limit by [contacting us](https://www.trigger.dev/contact).
+</Note>
+
+## Defining a queue
+
+As well as putting queue settings directly on a task, you can define a queue and reuse it across multiple tasks. This allows you to share the same concurrency limit:
+
+```ts /trigger/queue.ts
+const myQueue = queue({
+  name: "my-queue",
+  concurrencyLimit: 1,
+});
+
+export const task1 = task({
+  id: "task-1",
+  queue: {
+    name: "my-queue",
+  },
+  run: async (payload: { message: string }) => {
+    // ...
+  },
+});
+
+export const task2 = task({
+  id: "task-2",
+  queue: {
+    name: "my-queue",
+  },
+  run: async (payload: { message: string }) => {
+    // ...
+  },
+});
+```
+
+## Per-tenant queuing

docs/v3/environment-variables.mdx

@@ -69,7 +69,7 @@ A task is retried if an error is thrown, by default we retry 3 times.
 
 You can set the number of retries and the delay between retries in the `retry` field:
 
-```ts
+```ts /trigger/retry.ts
 export const taskWithRetries = task({
   id: "task-with-retries",
   retry: {
@@ -91,9 +91,9 @@ It's also worth mentioning that you can [retry a block of code](/v3/retrying) in
 
 ### `queue` options
 
-Queues allow you to control the concurrency of your tasks. The simplest use cases are to have [one-at-a-time](/v3/one-at-a-time) execution or lots of [parallel](/v3/parallelism) executions. There are more advanced situations where you want to [control the concurrency for different sets of your users](/v3/per-tenant). For more information read [the queues guide](/v3/concurrency).
+Queues allow you to control the concurrency of your tasks. This allows you to have one-at-a-time execution and parallel executions. There are also more advanced techniques like having different concurrencies for different sets of your users. For more information read [the concurrency & queues guide](/v3/queue-concurrency).
 
-```ts
+```ts /trigger/one-at-a-time.ts
 export const oneAtATime = task({
   id: "one-at-a-time",
   queue: {
@@ -109,7 +109,7 @@ export const oneAtATime = task({
 
 Some tasks require more vCPUs or GBs of RAM. You can specify these requirements in the `machine` field. For more information read [the machines guide](/v3/machines).
 
-```ts
+```ts /trigger/heavy-task.ts
 export const heavyTask = task({
   id: "heavy-task",
   machine: {