[red-knot] clarify mdtest README (#13720)

Address a potential point of confusion that bit a contributor in
#13719

Also remove a no-longer-accurate line about bare `error: ` assertions
(which are no longer allowed) and clarify another point about which
kinds of error assertions to use.

crates/red_knot_test/README.md

@@ -25,6 +25,15 @@ match the resulting diagnostics with the assertions in the test. Assertions are
 Python comments. If all diagnostics and all assertions are matched, the test passes; otherwise, it
 fails.
 
+<!---
+(If you are reading this document in raw Markdown source rather than rendered Markdown, note that
+the quadruple-backtick-fenced "markdown" language code block above is NOT itself part of the mdtest
+syntax, it's just how this README embeds an example mdtest Markdown document.)
+--->
+
+See actual example mdtest suites in
+[`crates/red_knot_python_semantic/resources/mdtest`](https://github.com/astral-sh/ruff/tree/main/crates/red_knot_python_semantic/resources/mdtest).
+
 ## Assertions
 
 Two kinds of assertions are supported: `# revealed:` (shown above) and `# error:`.
@@ -58,9 +67,8 @@ something about the behavior of importing it.)
 
 #### error
 
-A comment beginning with `# error:` is an assertion that a type checker diagnostic will
-be emitted, with text span starting on that line. If the comment is simply `# error:`, this will
-match any diagnostic. The matching can be narrowed in three ways:
+A comment beginning with `# error:` is an assertion that a type checker diagnostic will be emitted,
+with text span starting on that line. The matching can be narrowed in three ways:
 
 - `# error: [invalid-assignment]` requires that the matched diagnostic have the rule code
     `invalid-assignment`. (The square brackets are required.)
@@ -75,7 +83,8 @@ present; then contains-text, if present. For example, an assertion using all thr
 `# error: 8 [invalid-assignment] "Some text"`.
 
 Error assertions in tests intended to test type checker semantics should primarily use rule-code
-assertions, with occasional contains-text assertions where needed to disambiguate.
+assertions, with occasional contains-text assertions where needed to disambiguate or validate some
+details of the diagnostic message.
 
 ### Assertion locations