some rework

docs/pages/repo/docs/core-concepts/monorepos/running-tasks.mdx

@@ -17,7 +17,7 @@ Here, both `apps/web` and `apps/doc` use code from `packages/shared`. In fact, w
 
 ## Most tools don't optimize for speed
 
-Let's imagine we want to run all our tasks across all our workspaces. In a tool like `yarn`, you might run a script like this:
+Let's imagine we want to run all our tasks across all our workspaces. With a tool like `yarn`, you might run a script like this:
 
 ```
 yarn workspaces run lint
@@ -44,9 +44,9 @@ First, we declare our tasks inside `turbo.json`:
   "$schema": "https://turbo.build/schema.json",
   "pipeline": {
     "build": {
+      "outputs": [".next/**", "!.next/cache/**",".svelte-kit/**"],
       // ^build means build must be run in dependencies
       // before it can be run in this workspace
-      "outputs": [".next/**", "!.next/cache/**",".svelte-kit/**"],
       "dependsOn": ["^build"]
     },
     "test": {},
@@ -74,7 +74,8 @@ The `build` task inside `shared` completes first, then `web` and `docs` build af
 
 ## Defining a pipeline
 
-The `pipeline` configuration declares which tasks depend on each other in your monorepo. Here's a kitchen sink example:
+The `pipeline` configuration declares which tasks depend on each other in your
+monorepo. Here's a kitchen sink example:
 
 ```jsonc filename="turbo.json"
 {
@@ -109,6 +110,8 @@ The `pipeline` configuration declares which tasks depend on each other in your m
 }
 ```
 
+You can read more about how to setup your tasks in the next section on [Task Dependencies](/repo/docs/core-concepts/monorepos/task-dependencies).
+
 ## Running tasks from the root
 
 `turbo` can run tasks that exist in the `package.json` file at the root of the monorepo.
@@ -163,14 +166,14 @@ your `package.json` manifests. You can add scripts all at once, or one workspace
 at at a time. Turborepo will gracefully skip workspaces that don't include the
 task in their respective package.json manifest.
 
-For example, if your repository has three workspaces:
+For example, if your repository has the three workspaces (similar to the ones mentioned above on this page):
 
 ```bash
 apps/
   web/package.json
   docs/package.json
 packages/
-  ui/package.json
+  shared/package.json
 turbo.json
 package.json
 ```
@@ -211,7 +214,7 @@ task:
   </Tab>
   <Tab>
   ⚠️ Note the missing `build` script!
-   ```jsonc filename="packages/ui/package.json"
+   ```jsonc filename="packages/shared/package.json"
   {
     "name": "ui",
     "scripts": {}
@@ -225,4 +228,4 @@ turbo run build
 ```
 
 A turbo build will only execute the `build` script for the `web` and `docs` workspaces. The
-`ui` package will still be in the task graph, but will gracefully be skipped.
+`ui` package will still be part of the task graph, but will gracefully be skipped.

docs/pages/repo/docs/core-concepts/monorepos/task-dependencies.mdx

@@ -9,26 +9,19 @@ import { Tabs, Tab } from '../../../../../components/Tabs'
 
 # Task Dependencies
 
-Let's walk through some common patterns you'll want to get to know before diving in to `turbo.json`.
+Turborepo is most powerful when you express how your tasks relate to each other.
+We refer to these relationships as "dependencies", but they are not the same as
+package dependencies that you install from you `package.json` file. While Turbo
+does understand your workspaces, it does not automatically draw any
+relationships between their tasks, unless you express them in `turbo.json` via
+the `dependsOn` configuration. Through the rest of this page, if a `Task A` has
+a "dependency" on another `Task B`, it means that `Task B` will always run _before_ `Task A`.
 
-## No dependencies
-
-An empty dependency list (`dependsOn` is either undefined or `[]`) means that
-nothing needs to run before this task! After all, it has no dependencies.
-
-```jsonc filename="turbo.json"
-{
-  "$schema": "https://turbo.build/schema.json",
-  "pipeline": {
-    // A workspace's `lint` command has no dependencies and can be run any time.
-    "lint": {}
-  }
-}
-```
+Let's walk through some common patterns on how to make a task depend on other tasks.
 
-## In the same workspace
+## From the same workspace
 
-There might be tasks which need to run _before_ other tasks. For instance,
+There might be tasks that need to run _before_ other tasks. For instance,
 `build` might need to be run before `deploy`.
 
 If both tasks are in the same workspace, you can specify the relationship like
@@ -50,13 +43,19 @@ this:
 This means that whenever `turbo run deploy` is run, `build` will also be run
 inside the same workspace.
 
-## In a different workspace
+## From dependent workspaces
 
 A common pattern in monorepos is to declare that a workspace's `build` task
 should only run once the `build` tasks of all _the workspaces it depends on_ are
 complete.
 
-The `^` symbol explicitly declares that the task has a dependency on a task in a
+<Callout type="info">
+This one is confusing to talk about because it refers to both _workspace_ dependencies
+and _task_ dependencies, which are different concepts. Workspace dependencies are `dependencies`
+and `devDependencies` in `package.json`, whereas, task dependencies are `dependsOn` key in `turbo.json`.
+</Callout>
+
+The `^` symbol (called a "caret") explicitly declares that the task depends on the task in a
 workspace it depends on.
 
 ```jsonc filename="turbo.json"
@@ -67,15 +66,17 @@ workspace it depends on.
       // "A workspace's `build` command depends on its dependencies'
       // and devDependencies' `build` commands being completed first"
       "dependsOn": ["^build"],
-      "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"]
     }
   }
 }
 ```
 
-## Specific Tasks from a Workspace
+With the configuration above, if an app installs a package from another workspace, the package's
+`build` script will always run before the app's `build` script.
 
-Sometimes, you may want to create a workspace-task dependency on another
+## From arbitrary workspaces
+
+Sometimes, you may want to create a workspace-task depend on another
 workspace-task. This can be especially helpful for repos migrating from `lerna`
 or `rush`, where tasks are run in separate phases by default. Sometimes these
 configurations make assumptions that cannot be expressed in a simple `pipeline`
@@ -113,7 +114,7 @@ finished.
    generally recommend using it for deployment orchestration tasks such as
    health checks, rather than build-time dependencies, so that Turborepo can
    optimize these tasks more efficiently
-1. Package-tasks do not inherit cache configuration. You must redeclare
+1. Workspace-tasks do not inherit cache configuration. You must redeclare
    [`outputs`](/repo/docs/reference/configuration#outputs) at the moment.
 1. `<workspace>` must match the `name` key in the workspace's `package.json` or
    the task will be ignored.
@@ -172,3 +173,18 @@ tree.
   Shoutout to [Kenneth Chau](https://twitter.com/kenneth_chau) for the idea of
   fanning out tasks in such a concise and elegant way.
 </Callout>
+
+## No dependencies
+
+An empty dependency list (`dependsOn` is either undefined or `[]`) means that
+nothing needs to run before this task! After all, it has no dependencies.
+
+```jsonc filename="turbo.json"
+{
+  "$schema": "https://turbo.build/schema.json",
+  "pipeline": {
+    // A workspace's `lint` command has no dependencies and can be run any time.
+    "lint": {}
+  }
+}
+```