Merge pull request #2970 from johnduffell/patch-1

Clearer points in favour of macro mixing

Author: sjrd

_overviews/scala3-migration/compatibility-metaprogramming.md

@@ -63,7 +63,10 @@ You can learn all the new metaprogramming concepts by reading the [Macros in Sca
 ## Cross-building a Macro Library
 
 You have written a wonderful macro library and you would like it to be available in Scala 2.13 and Scala 3.
-There are two different approaches, the traditional cross-building technique and the more experimental mixing macro technique.
+There are two different approaches, the traditional cross-building technique and the more flexible macro mixing technique.
+
+The benefit of macro mixing is that consumers who take advantage of the `-Ytasty-reader` option can still use your macros.
+
 You can learn about them by reading these tutorials:
 - [Cross-Building a Macro Library](tutorial-macro-cross-building.html)
 - [Mixing Scala 2.13 and Scala 3 Macros](tutorial-macro-mixing.html)

_overviews/scala3-migration/tutorial-macro-mixing.md

@@ -7,10 +7,12 @@ previous-page: tutorial-macro-mixing
 next-page: tooling-syntax-rewriting
 ---
 
-This tutorial shows how to mix Scala 2.13 and Scala 3 macros in a single artifact.
+This tutorial shows how to mix Scala 2.13 and Scala 3 macros in a single artifact.  This means that consumers can use '-Ytasty-reader' from Scala 2.13 code that uses your macros.
 
-It can be used to create a new Scala 3 macro library and make it available for Scala 2.13 users.
-It can also be used to port an existing Scala 2.13 macro library to Scala 3, although it is probably easier to cross-build.
+There are two main benefits of this:
+
+1. Making a new or existing scala 3 macro library available for Scala 2.13 users without having to provide a separate 2.13 version
+2. Allowing your macros to be usable in multi-project builds that are being upgraded module by module.
 
 ## Introduction