diff --git a/docs/pyproject.md b/docs/pyproject.md
index 09387125cbe..340a0518a91 100644
--- a/docs/pyproject.md
+++ b/docs/pyproject.md
@@ -723,6 +723,7 @@ for more information on other keys and specifying version ranges.
 ### scripts
 
 **Deprecated**: Use `project.scripts` instead.
+Use `[tool.poetry.scripts]` only for scripts of type "file", because those are not supported in `[project.scripts]`.
 
 This section describes the scripts or executables that will be installed when installing the package
 
@@ -742,12 +743,12 @@ When a script is added or updated, run `poetry install` to make them available i
 my_executable = { reference = "some_binary.exe", type = "file" }
 ```
 
-With this configuration, Poetry will look for the referenced file in the active project and then copy it to the OS installation directory.
+This tells Poetry to include the specified file, relative to your project directory, in distribution builds. It will then be copied to the appropriate installation directory for your operating system when your package is installed.
 
 * On Windows the file is placed in the `Scripts/` directory.
 * On *nix system the file is placed in the `bin/` directory.
 
-## `extras`
+### `extras`
 
 **Deprecated**: Use `project.optional-dependencies` instead.