[GR-27032] Rename the Jython guide to migration guide

PullRequest: graalpython/1365

Author: timfel

docs/user/FAQ.md

@@ -9,7 +9,7 @@ The GraalVM team continues to improve the number of passing CPython unittests, a
 ### Can the GraalVM Python runtime replace my Jython use case?
 
 It can, but there are some caveats, like Python code subclassing Java classes or use through the `javax.script.ScriptEngine` not being supported.
-See the [Jython Compatibility](Jython.md) guide for details.
+See the [Jython Migration](Jython.md) guide for details.
 
 ### Do I need to compile and run native modules as LLVM bitcode to use on GraalVM's Python runtime?
 

docs/user/Jython.md

@@ -1,11 +1,19 @@
-# Jython Compatibility
+# Jython Migration Guide
 
 Most Jython code that uses Java integration will be based on a
 stable Jython release, and these only come in Python 2.x versions.
 GraalVM's Python runtime, in contrast, is only targeting Python 3.x.
-Thus, GraalVM does not provide full compatibility with these earlier 2.x versions of Jython.
+GraalVM does not provide a full compatibility with these earlier 2.x versions of Jython.
+Thus, a significant migration step will have to be taken to migrate all your code to Python 3.
 
-Nonetheless, there are certain features of Jython's Java integration that we can offer similarly.
+For Jython specific features, follow this document to learn about migration to GraalVM's Python runtime.
+
+Note that some features of Jython have a negative impact on runtime performance, and are disabled by default.
+To make migration easier, you can enable some features with a command line flag on GraalVM: `--python.EmulateJython`.
+
+## Importing Java Packages
+
+There are certain features of Jython's Java integration that are enabled by default on GraalVM's Python runtime.
 Here is an example:
 
     >>> import java.awt as awt
@@ -17,23 +25,21 @@ Here is an example:
     >>> win.show()
 
 This example works exactly the same on both Jython and Python on GraalVM.
-Some features of Jython are more expensive at runtime, and thus are hidden behind a
-command line flag on GraalVM: `--python.EmulateJython`.
-
-## Import Java Classes
-
-Import statements allow you to import Java classes, but (unlike Jython), only
-packages in the `java` namespace can be directly imported.
+However, on GraalVM only packages in the `java` namespace can be directly imported.
+Importing classes from packages outside the `java` namespace also requires the `--python.EmulateJython` option to be active.
 
+Additionally, importing Java packages as Python modules is only supported under very specific circumstances.
 For example, this will work:
 ```python
 import java.lang as lang
 ```
+
 But this will not:
 ```python
 import javax.swing as swing
 from javax.swing import *
 ```
+
 Instead, you will have to import one of the classes you are interested in directly:
 ```python
 import javax.swing.Window as Window