From c193f6b03cba159e32bc3ba4bd39c33c2c1ac21d Mon Sep 17 00:00:00 2001
From: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
Date: Tue, 28 Jan 2025 15:01:12 +0100
Subject: [PATCH] Update README.asciidoc (#96455) (#121028)

Co-authored-by: ARPIT SHARMA <93235104+ARPIT2128@users.noreply.github.com>
---
 docs/README.asciidoc | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/docs/README.asciidoc b/docs/README.asciidoc
index 9b7e280e532f..05f449795c7f 100644
--- a/docs/README.asciidoc
+++ b/docs/README.asciidoc
@@ -157,16 +157,15 @@ used for its modifiers:
   * `// TESTRESPONSE[skip:reason]`: Skip the assertions specified by this
   response.
 * `// TESTSETUP`: Marks this snippet as the "setup" for all other snippets in
-  this file. This is a somewhat natural way of structuring documentation. You
-  say "this is the data we use to explain this feature" then you add the
-  snippet that you mark `// TESTSETUP` and then every snippet will turn into
-  a test that runs the setup snippet first. See the "painless" docs for a file
-  that puts this to good use. This is fairly similar to `// TEST[setup:name]`
-  but rather than the setup defined in `docs/build.gradle` the setup is defined
-  right in the documentation file. In general, we should prefer `// TESTSETUP`
-  over `// TEST[setup:name]` because it makes it more clear what steps have to
-  be taken before the examples will work. Tip: `// TESTSETUP` can only be used
-  on the first snippet of a document.
+  this file. In order to enhance clarity and simplify understanding for readers,
+  a straightforward approach involves marking the first snippet in the documentation file with the 
+  `// TESTSETUP` marker. By doing so, it clearly indicates that this particular snippet serves as the setup 
+  or preparation step for all subsequent snippets in the file. 
+  This helps in explaining the necessary steps that need to be executed before running the examples.
+  Unlike the alternative convention `// TEST[setup:name]`, which relies on a setup defined in a separate file,
+  this convention brings the setup directly into the documentation file, making it more self-contained and reducing ambiguity.
+  By adopting this convention, users can easily identify and follow the correct sequence 
+  of steps to ensure that the examples provided in the documentation work as intended.
 * `// TEARDOWN`: Ends and cleans up a test series started with `// TESTSETUP` or
   `// TEST[setup:name]`. You can use `// TEARDOWN` to set up multiple tests in
   the same file.