Add more deprecation info

Closes #4102

Author: coke

doc/Type/Routine.pod6

@@ -165,6 +165,8 @@ Calculating 43th prime
 191
 =end code
 
+Marks something as I<deprecated>
+
 =head2 trait is pure
 
     multi sub trait_mod:<is>(Routine $r, :$pure!)
@@ -284,7 +286,14 @@ for more details.
 
     multi sub trait_mod:<is>(Routine:D $r, :$DEPRECATED!)
 
-Marks a routine as deprecated, optionally with a message what to use instead.
+Marks a C<Routine> as deprecated; that is, it should no longer be used going forward,
+and will eventually be removed. An optional message specifying the replacement
+functionality can be specified
+
+By having both the original (deprecated) and new C<Routine> available simultaneously,
+you can avoid a breaking change in a single release, by allowing users time and instructions
+on how to update their code. Remove the deprecated verison only after at least
+one release that includes both the warning and the new C<Routine>.
 
 This code