[docs] Reorganize information on utility scripts (#18296)
The project's top-level README.md file contains a good deal of
information which may not be relevant to all readers. This risks
overwhelming newcomers, and it also discourages referencing the content
in more targeted contexts from the project's documentation website.
Move the information on command-line utility scripts from the top-level
README.md file to a dedicated document within the docs/ directory.
diff --git a/README.md b/README.md
index 5054889..5bd9468 100644
--- a/README.md
+++ b/README.md
@@ -339,36 +339,6 @@
[lint-tool]: https://web-platform-tests.org/writing-tests/lint-tool.html
-Adding command-line scripts ("tools" subdirs)
----------------------------------------------
-
-Sometimes you may want to add a script to the repository that's meant
-to be used from the command line, not from a browser (e.g., a script
-for generating test files). If you want to ensure (e.g., for security
-reasons) that such scripts won't be handled by the HTTP server, but
-will instead only be usable from the command line, then place them in
-either:
-
-* the `tools` subdir at the root of the repository, or
-
-* the `tools` subdir at the root of any top-level directory in the
- repository which contains the tests the script is meant to be used
- with
-
-Any files in those `tools` directories won't be handled by the HTTP
-server; instead the server will return a 404 if a user navigates to
-the URL for a file within them.
-
-If you want to add a script for use with a particular set of tests but
-there isn't yet any `tools` subdir at the root of a top-level
-directory in the repository containing those tests, you can create a
-`tools` subdir at the root of that top-level directory and place your
-scripts there.
-
-For example, if you wanted to add a script for use with tests in the
-`notifications` directory, create the `notifications/tools` subdir and
-put your script there.
-
Test Review
===========
diff --git a/docs/writing-tests/index.md b/docs/writing-tests/index.md
index 8af5aef..b9ed4a8 100644
--- a/docs/writing-tests/index.md
+++ b/docs/writing-tests/index.md
@@ -26,6 +26,7 @@
testdriver
testdriver-tutorial
testharness
+ tools
visual
wdspec
```
diff --git a/docs/writing-tests/tools.md b/docs/writing-tests/tools.md
new file mode 100644
index 0000000..0a9a7dc
--- /dev/null
+++ b/docs/writing-tests/tools.md
@@ -0,0 +1,25 @@
+# Command-line utility scripts
+
+Sometimes you may want to add a script to the repository that's meant to be
+used from the command line, not from a browser (e.g., a script for generating
+test files). If you want to ensure (e.g., for security reasons) that such
+scripts won't be handled by the HTTP server, but will instead only be usable
+from the command line, then place them in either:
+
+* the `tools` subdir at the root of the repository, or
+
+* the `tools` subdir at the root of any top-level directory in the repository
+ which contains the tests the script is meant to be used with
+
+Any files in those `tools` directories won't be handled by the HTTP server;
+instead the server will return a 404 if a user navigates to the URL for a file
+within them.
+
+If you want to add a script for use with a particular set of tests but there
+isn't yet any `tools` subdir at the root of a top-level directory in the
+repository containing those tests, you can create a `tools` subdir at the root
+of that top-level directory and place your scripts there.
+
+For example, if you wanted to add a script for use with tests in the
+`notifications` directory, create the `notifications/tools` subdir and put your
+script there.
