Polish @timeout documentation in User Guide

Author: sbrannen

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -1614,9 +1614,9 @@ implementations.
 WARNING: You're invited to give it a try and provide feedback to the JUnit team so they
 can improve and eventually <<api-evolution, promote>> this feature.
 
-The `@Timeout` annotation allows to declare that a test, test factory, test template, or
-lifecycle method should fail if its execution time exceeds a given duration, and
-optionally a time unit (seconds are used by default).
+The `@Timeout` annotation allows one to declare that a test, test factory, test template,
+or lifecycle method should fail if its execution time exceeds a given duration. The time
+unit for the duration defaults to seconds but is configurable.
 
 The following example shows how `@Timeout` is applied to lifecycle and test methods.
 
@@ -1628,23 +1628,23 @@ include::{testDir}/example/TimeoutDemo.java[tags=user_guide]
 Contrary to the `assertTimeoutPreemptively()` assertion, the execution of the annotated
 method proceeds in the main thread of the test. If the timeout is exceeded, the main
 thread is interrupted from another thread. This is done to ensure interoperability with
-frameworks such as Spring that make extensive use of mechanisms that are sensitive to the
-currently running thread (e.g. `ThreadLocals`).
+frameworks such as Spring that make use of mechanisms that are sensitive to the currently
+running thread — for example, `ThreadLocal` transaction management.
 
-To apply the same timeout to all test methods within a test class and all its `@Nested`
-classes, you can declare the `@Timeout` annotation on the class level. It will then be
+To apply the same timeout to all test methods within a test class and all of its `@Nested`
+classes, you can declare the `@Timeout` annotation at the class level. It will then be
 applied to all test, test factory, and test template methods within that class and its
-`@Nested` classes unless overridden by a `@Timeout` annotation on a method or `@Nested`
-class. Please note that `@Timeout` annotations declared on the class level are not
-applied to lifecycle methods.
+`@Nested` classes unless overridden by a `@Timeout` annotation on a specific method or
+`@Nested` class. Please note that `@Timeout` annotations declared at the class level are
+not applied to lifecycle methods.
 
-Declaring `@Timeout` on a test factory method checks that the method returns within the
-specified duration but does verify the execution time of the returned `DynamicTests`.
-Please use `assertTimeout()`/`assertTimeoutPreemptively()` for that purpose.
+Declaring `@Timeout` on a `@TestFactory` method checks that the factory method returns
+within the specified duration but does verify the execution time of each individual
+`DynamicTest` generated by the factory. Please use
+`assertTimeout()` or `assertTimeoutPreemptively()` for that purpose.
 
-If `@Timeout` is present on a test template method, such as a method annotated with
-`@RepeatedTest` or `@ParameterizedTest`, each invocation is checked to finish within the
-given timeout.
+If `@Timeout` is present on a `@TestTemplate` method — for example, a `@RepeatedTest` or
+`@ParameterizedTest` — each invocation will have the given timeout applied to it.
 
 The following <<running-tests-config-params, configuration parameters>> can be used to
 specify global timeouts for all methods of a certain category unless they or an enclosing