Clarifies the dev-dependencies -> group.dev.dependencies switch in do…

…cs (#6723)

As written, it seemed to prioritize the older section notation without
clarifying that the older syntax still works but shouldn't be used. This
reorder visually prioritizes the preferred syntax as of 1.2.x while
clearly explaining what the old syntax is during this transition period.

The best next step here would be clearly defining the version in which
dev-dependencies will disappear.

Co-authored-by: Mathieu Kniewallner <mathieu.kniewallner@gmail.com>
(cherry picked from commit b1e1e14)

docs/managing-dependencies.md

@@ -59,19 +59,24 @@ use [extras]({{< relref "pyproject#extras" >}}) instead. Extras can be installed
 {{% /note %}}
 
 {{% note %}}
-**A note about the `dev-dependencies` section**
+**A note about defining a `dev` dependencies group**
 
-Any dependency declared in the `dev-dependencies` section will automatically be added to a `dev` group.
-So the two following notations are equivalent:
+The proper way to define a `dev` dependencies group since Poetry 1.2.0 is the following:
 
 ```toml
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 pytest = "^6.0.0"
 pytest-mock = "*"
 ```
 
+This group notation is preferred since Poetry 1.2.0 and not usable in earlier versions.
+For backwards compatibility with older versions of Poetry,
+any dependency declared in the `dev-dependencies` section will automatically be added to the `dev` group.
+So the above and following notations are equivalent:
+
 ```toml
-[tool.poetry.group.dev.dependencies]
+# Poetry pre-1.2.x style, understood by Poetry 1.0–1.2
+[tool.poetry.dev-dependencies]
 pytest = "^6.0.0"
 pytest-mock = "*"
 ```