diff --git a/src/doc/rustc-dev-guide/src/tests/ui.md b/src/doc/rustc-dev-guide/src/tests/ui.md
index 9bfc60e08a6ea..b1feef9ed0cc8 100644
--- a/src/doc/rustc-dev-guide/src/tests/ui.md
+++ b/src/doc/rustc-dev-guide/src/tests/ui.md
@@ -309,7 +309,8 @@ fn main((ؼ
 
 Use `//~?` to match an error without line information.
 `//~?` is precise and will not match errors if their line information is available.
-It should be preferred to using `error-pattern`, which is imprecise and non-exhaustive.
+For tests wishing to match against compiler diagnostics, error annotations should
+be preferred over //@ error-pattern, //@ error-pattern is imprecise and non-exhaustive.
 
 ```rust,ignore
 //@ compile-flags: --print yyyy
@@ -347,8 +348,6 @@ fn main() {
 }
 ```
 
-Use of `error-pattern` is not recommended in general.
-
 For strict testing of compile time output, try to use the line annotations `//~` as much as
 possible, including `//~?` annotations for diagnostics without spans.
 
@@ -359,7 +358,8 @@ Some of the compiler messages can stay uncovered by annotations in this mode.
 
 For checking runtime output, `//@ check-run-results` may be preferable.
 
-Only use `error-pattern` if none of the above works.
+Only use `error-pattern` if none of the above works, such as when finding a
+specific string pattern in a runtime panic output.
 
 Line annotations `//~` and `error-pattern` are compatible and can be used in the same test.
 
diff --git a/tests/ui/SUMMARY.md b/tests/ui/README.md
similarity index 100%
rename from tests/ui/SUMMARY.md
rename to tests/ui/README.md