From 136fb996d11ad6d41dfa8897c1b06bbab623a445 Mon Sep 17 00:00:00 2001
From: Romario Nijim <75387323+Romarionijim@users.noreply.github.com>
Date: Fri, 21 Jun 2024 20:20:56 +0300
Subject: [PATCH] docs: added more explanation to sharding to make it more
 understandable. (#31399)

* added more explanation to the sharding section for it to be more
understandable what it is and what it's purpose.
* because from the explanation in the docs. - it sound like that a
"shard" is a machine that is provided by playwright in addition to the
current setup , like a managed machine, but in reality it is simply a
separate job in the CI, dividing tests to separate jobs is sharding,
which sounds a lot easier when you think about it this way because it
could be confusing at the beginning IMO.
---
 docs/src/test-sharding-js.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/src/test-sharding-js.md b/docs/src/test-sharding-js.md
index 068b7172d0..d0312db811 100644
--- a/docs/src/test-sharding-js.md
+++ b/docs/src/test-sharding-js.md
@@ -5,7 +5,11 @@ title: "Sharding"
 
 ## Introduction
 
-By default, Playwright runs test files in [parallel](./test-parallel.md) and strives for optimal utilization of CPU cores on your machine. In order to achieve even greater parallelisation, you can further scale Playwright test execution by running tests on multiple machines simultaneously. We call this mode of operation "sharding".
+By default, Playwright runs test files in [parallel](./test-parallel.md) and strives for optimal utilization of CPU cores on your machine. In order to achieve even greater parallelisation, you can further scale Playwright test execution by running tests on multiple machines simultaneously. We call this mode of operation "sharding". Sharding in Playwright means splitting your tests into smaller parts called "shards". Each shard is like a separate job that can run independently. The whole purpose is to divide your tests to speed up test runtime.
+
+When you shard your tests, each shard can run on its own, utilizing the available CPU cores. This helps speed up the testing process by doing tasks simultaneously.
+
+In a CI pipeline, each shard can run as a separate job, making use of the hardware resources available in your CI pipeline, like CPU cores, to run tests faster.
 
 ## Sharding tests between multiple machines
 
@@ -18,7 +22,7 @@ npx playwright test --shard=3/4
 npx playwright test --shard=4/4
 ```
 
-Now, if you run these shards in parallel on different computers, your test suite completes four times faster.
+Now, if you run these shards in parallel on different jobs, your test suite completes four times faster.
 
 Note that Playwright can only shard tests that can be run in parallel. By default, this means Playwright will shard test files. Learn about other options in the [parallelism guide](./test-parallel.md).