Improve changelog note about markers

Also changed the title in the docs because the previous title had
the same level as the title, making it appear in a separate entry
in `contents.rst`

changelog/3317.feature

@@ -1 +1,3 @@
-introduce correct per node mark handling and deprecate the always incorrect existing mark handling
+Revamp the internals of the ``pytest.mark`` implementation with correct per node handling and introduce a new ``Node.iter_markers``
+API for mark iteration over nodes which fixes a number of long standing bugs caused by the old approach. More details can be
+found in `the marks documentation <https://docs.pytest.org/en/latest/mark.html#marker-revamp-and-iteration>`_.

doc/en/contents.rst

@@ -15,12 +15,12 @@ Full pytest documentation
    existingtestsuite
    assert
    fixture
+   mark
    monkeypatch
    tmpdir
    capture
    warnings
    doctest
-   mark
    skipping
    parametrize
    cache

doc/en/mark.rst

@@ -34,8 +34,8 @@ which also serve as documentation.
 
 .. `marker-iteration`
 
-Marker iteration
-=================
+Marker revamp and iteration
+---------------------------
 
 .. versionadded:: 3.6