diff --git a/changelog/3317.feature b/changelog/3317.feature
index be4625c6e..b7f947af8 100644
--- a/changelog/3317.feature
+++ b/changelog/3317.feature
@@ -1 +1,3 @@
-introduce correct per node mark handling and deprecate the always incorrect existing mark handling
\ No newline at end of file
+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>`_.
diff --git a/doc/en/contents.rst b/doc/en/contents.rst
index 79c4fce3e..38a4be941 100644
--- a/doc/en/contents.rst
+++ b/doc/en/contents.rst
@@ -15,12 +15,12 @@ Full pytest documentation
    existingtestsuite
    assert
    fixture
+   mark
    monkeypatch
    tmpdir
    capture
    warnings
    doctest
-   mark
    skipping
    parametrize
    cache
diff --git a/doc/en/mark.rst b/doc/en/mark.rst
index bee60f923..bd416479d 100644
--- a/doc/en/mark.rst
+++ b/doc/en/mark.rst
@@ -34,8 +34,8 @@ which also serve as documentation.
 
 .. `marker-iteration`
 
-Marker iteration
-=================
+Marker revamp and iteration
+---------------------------
 
 .. versionadded:: 3.6