docs(nx-cloud): add why nx cloud page (#22449)

Co-authored-by: Miroslav Jonaš <missing.manual@gmail.com>
Co-authored-by: isaacplmann

docs/generated/manifests/ci.json

@@ -17,6 +17,17 @@
         "path": "/ci/intro/ci-with-nx",
         "tags": []
       },
+      {
+        "id": "why-nx-cloud",
+        "name": "Why Nx Cloud?",
+        "description": "",
+        "mediaImage": "",
+        "file": "nx-cloud/intro/why-nx-cloud",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/ci/intro/why-nx-cloud",
+        "tags": []
+      },
       {
         "id": "tutorials",
         "name": "Tutorials",
@@ -67,6 +78,17 @@
     "path": "/ci/intro/ci-with-nx",
     "tags": []
   },
+  "/ci/intro/why-nx-cloud": {
+    "id": "why-nx-cloud",
+    "name": "Why Nx Cloud?",
+    "description": "",
+    "mediaImage": "",
+    "file": "nx-cloud/intro/why-nx-cloud",
+    "itemList": [],
+    "isExternal": false,
+    "path": "/ci/intro/why-nx-cloud",
+    "tags": []
+  },
   "/ci/intro/tutorials": {
     "id": "tutorials",
     "name": "Tutorials",
@@ -133,7 +155,7 @@
       {
         "id": "affected",
         "name": "Run Only Tasks Affected by a PR",
-        "description": "",
+        "description": "This allows to only run tasks on projects that got changed in a given PR.",
         "mediaImage": "",
         "file": "shared/using-nx/affected",
         "itemList": [],
@@ -166,7 +188,7 @@
       {
         "id": "dynamic-agents",
         "name": "Dynamically Allocate Agents",
-        "description": "",
+        "description": "Learn how to dynamically allocate agents based on the size of a PR, keeping the balance of speed and cost.",
         "mediaImage": "",
         "file": "nx-cloud/features/dynamic-agents",
         "itemList": [],
@@ -177,7 +199,7 @@
       {
         "id": "split-e2e-tasks",
         "name": "Automatically Split E2E Tasks (Atomizer)",
-        "description": "",
+        "description": "Learn how Nx can automatically split e2e tests into fine-grained chunks for a much better distribution on Nx Agents.",
         "mediaImage": "",
         "file": "nx-cloud/features/split-e2e-tasks",
         "itemList": [],
@@ -188,7 +210,7 @@
       {
         "id": "flaky-tasks",
         "name": "Identify and Re-run Flaky Tasks",
-        "description": "",
+        "description": "Learn how Nx Cloud is able to automatically identify flaky tasks and re-run them for you.",
         "mediaImage": "",
         "file": "nx-cloud/features/flaky-tasks",
         "itemList": [],
@@ -215,7 +237,7 @@
   "/ci/features/affected": {
     "id": "affected",
     "name": "Run Only Tasks Affected by a PR",
-    "description": "",
+    "description": "This allows to only run tasks on projects that got changed in a given PR.",
     "mediaImage": "",
     "file": "shared/using-nx/affected",
     "itemList": [],
@@ -248,7 +270,7 @@
   "/ci/features/dynamic-agents": {
     "id": "dynamic-agents",
     "name": "Dynamically Allocate Agents",
-    "description": "",
+    "description": "Learn how to dynamically allocate agents based on the size of a PR, keeping the balance of speed and cost.",
     "mediaImage": "",
     "file": "nx-cloud/features/dynamic-agents",
     "itemList": [],
@@ -259,7 +281,7 @@
   "/ci/features/split-e2e-tasks": {
     "id": "split-e2e-tasks",
     "name": "Automatically Split E2E Tasks (Atomizer)",
-    "description": "",
+    "description": "Learn how Nx can automatically split e2e tests into fine-grained chunks for a much better distribution on Nx Agents.",
     "mediaImage": "",
     "file": "nx-cloud/features/split-e2e-tasks",
     "itemList": [],
@@ -270,7 +292,7 @@
   "/ci/features/flaky-tasks": {
     "id": "flaky-tasks",
     "name": "Identify and Re-run Flaky Tasks",
-    "description": "",
+    "description": "Learn how Nx Cloud is able to automatically identify flaky tasks and re-run them for you.",
     "mediaImage": "",
     "file": "nx-cloud/features/flaky-tasks",
     "itemList": [],

docs/generated/manifests/menus.json

@@ -5661,6 +5661,14 @@
             "children": [],
             "disableCollapsible": false
           },
+          {
+            "name": "Why Nx Cloud?",
+            "path": "/ci/intro/why-nx-cloud",
+            "id": "why-nx-cloud",
+            "isExternal": false,
+            "children": [],
+            "disableCollapsible": false
+          },
           {
             "name": "Tutorials",
             "path": "/ci/intro/tutorials",
@@ -5697,6 +5705,14 @@
         "children": [],
         "disableCollapsible": false
       },
+      {
+        "name": "Why Nx Cloud?",
+        "path": "/ci/intro/why-nx-cloud",
+        "id": "why-nx-cloud",
+        "isExternal": false,
+        "children": [],
+        "disableCollapsible": false
+      },
       {
         "name": "Tutorials",
         "path": "/ci/intro/tutorials",

docs/generated/manifests/tags.json

@@ -71,7 +71,7 @@
       "path": "/recipes/running-tasks/workspace-watching"
     },
     {
-      "description": "",
+      "description": "This allows to only run tasks on projects that got changed in a given PR.",
       "file": "shared/using-nx/affected",
       "id": "affected",
       "name": "Run Only Tasks Affected by a PR",

docs/map.json

@@ -1665,6 +1665,11 @@
               "id": "ci-with-nx",
               "file": "nx-cloud/intro/ci-with-nx"
             },
+            {
+              "name": "Why Nx Cloud?",
+              "id": "why-nx-cloud",
+              "file": "nx-cloud/intro/why-nx-cloud"
+            },
             {
               "name": "Tutorials",
               "id": "tutorials",
@@ -1691,6 +1696,7 @@
           "itemList": [
             {
               "name": "Run Only Tasks Affected by a PR",
+              "description": "This allows to only run tasks on projects that got changed in a given PR.",
               "tags": ["run-tasks"],
               "id": "affected",
               "file": "shared/using-nx/affected"
@@ -1710,17 +1716,20 @@
             },
             {
               "name": "Dynamically Allocate Agents",
+              "description": "Learn how to dynamically allocate agents based on the size of a PR, keeping the balance of speed and cost.",
               "id": "dynamic-agents",
               "file": "nx-cloud/features/dynamic-agents"
             },
             {
               "name": "Automatically Split E2E Tasks (Atomizer)",
               "id": "split-e2e-tasks",
+              "description": "Learn how Nx can automatically split e2e tests into fine-grained chunks for a much better distribution on Nx Agents.",
               "file": "nx-cloud/features/split-e2e-tasks"
             },
             {
               "name": "Identify and Re-run Flaky Tasks",
               "id": "flaky-tasks",
+              "description": "Learn how Nx Cloud is able to automatically identify flaky tasks and re-run them for you.",
               "file": "nx-cloud/features/flaky-tasks"
             },
             {

docs/nx-cloud/intro/ci-with-nx.md

@@ -1,6 +1,6 @@
 # Continuous Integration with Nx
 
-When implemented well, continuous integration (CI) allows a team of developers to efficiently make changes to a codebase with the confidence that they haven't broken existing functionality. When implemented poorly, CI slows down the team by adding obstacles to deploying code without actually providing any confidence that the code is correct.
+Implementing an efficient CI setup for monorepos - while crucial - can be challenging and maintenance heavy. That is [not your fault, though](/ci/intro/why-nx-cloud). Nx Cloud comes with a series of features that help make CI for monorepos faster, more reliable and more cost-effective.
 
 ## Core Features
 

docs/nx-cloud/intro/why-nx-cloud.md

@@ -0,0 +1,63 @@
+# Why Nx Cloud?
+
+{% youtube
+src="https://youtu.be/4VI-q943J3o"
+title="Fast CI for monorepos"
+width="100%" /%}
+
+If CI feels challenging to you, **it might not be your fault**. It's a fundamental issue with how the current, traditional CI execution model works. Nx Cloud adopts a new **task-based** CI model which allows you to overcome both the slowness and unreliability of the current VM-based CI model. _(Dive deeper into the task based CI execution model [in this blog post](https://blog.nrwl.io/reliable-ci-a-new-execution-model-fixing-both-flakiness-and-slowness-6849fd4b4037))_
+
+Nx Cloud addresses critical aspects of CI/CD, including:
+
+- **speed** - 30% - 70% faster CI (based on reports from our clients)
+- **cost** - 40% - 75% reduction in CI costs (observed on the Nx OSS monorepo)
+- **reliability** - by automatically identifying flaky tasks (e2e tests in particular) and re-running them
+
+## How?
+
+Nx Cloud follows a task-based CI model which is **not just fast but also robust**. Instead of statically assigning work to machines (as in a traditional CI model), you can imagine a **pile of tasks which get picked up automatically** by agents on the Nx Cloud infrastructure. There's **no static assignment, agents coordinate the work by themselves**. If an agent fails during the setup phase, other agents will pick up its work. If more work needs to be done, more agents will be started to still guarantee a fast execution, if less work is needed, fewer agents will be started to save resources.
+
+All this is possible because Nx Cloud directly integrates with Nx and has knowledge about the project structure and tasks as well as dependencies among them.
+
+Read more about individual features of Nx Cloud in the [features section](/ci/features).
+
+## How does Nx Cloud integrate into my existing CI setup
+
+Nx Cloud directly integrates with your existing CI setup.
+
+![Nx Cloud Overview](/shared/images/nx-cloud/nx-cloud-overview.webp)
+
+In a nutshell, here's how this works:
+
+**Step 1: Connect your workspace to Nx Cloud**
+
+This can be done by signing up on [nx.app](https://nx.app) and then connecting to your git repository. Read more about all the details [on this doc page](/ci/recipes/set-up/connect-to-cloud).
+
+**Step 2: Your CI script triggers Nx Cloud**
+
+```yml
+- name: Start CI run
+  run: 'npx nx-cloud start-ci-run --distribute-on="8 linux-medium-js"'
+```
+
+Check out our [recipes for the various CI providers](/ci/recipes/set-up).
+
+**Step 3: Run your Nx command as usual**
+
+```yml
+- run: npx nx-cloud record -- nx format:check
+- run: npx nx affected -t lint test build e2e-ci
+```
+
+All these commands are automatically picked up by Nx Cloud, split up into smaller tasks and distributed across the specified number of machines.
+
+**Step 4: All results are played back automatically**
+
+Nx Cloud automatically plays back all results to your CI system, as if distribution never happened. You can continue doing post-processing on the results, like uploading test reports, deploying artifacts etc.
+
+## Learn more
+
+- [Blog post: Reliable CI: A new execution model fixing both flakiness and slowness](https://blog.nrwl.io/reliable-ci-a-new-execution-model-fixing-both-flakiness-and-slowness-6849fd4b4037?source=friends_link&sk=6747bb77c92772a5f885a61127cb5c0b)
+- [Live stream: Unlock the secret of fast CI - Hands-on session](https://www.youtube.com/live/rkLKaqLeDa0)
+- [Webinar: Nx Agents Walkthrough: Effortlessly Fast CI Built for Monorepos](https://go.nx.dev/march-webinar?utm_source=nx_cloud&utm_medium=nxdocs&utm_campaign=nx_agents&utm_id=devrel)
+- [Youtube: 10x Faster e2e Tests](https://www.youtube.com/watch?v=0YxcxIR7QU0)

docs/shared/reference/sitemap.md

@@ -263,6 +263,7 @@
 
   - [Intro](/ci/intro)
     - [CI with Nx](/ci/intro/ci-with-nx)
+    - [Why Nx Cloud?](/ci/intro/why-nx-cloud)
     - [Tutorials](/ci/intro/tutorials)
       - [Circle CI with Nx](/ci/intro/tutorials/circle)
       - [GitHub Actions with Nx](/ci/intro/tutorials/github-actions)