diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index a9ca65d370..3e3df0d2b6 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -126,6 +126,7 @@ content_files =					\
 	directfb.sgml				\
 	drawing-model.xml			\
 	glossary.xml				\
+	migrating-2to3.xml			\
 	migrating-checklist.sgml		\
         migrating-ClientSideWindows.sgml	\
 	migrating-GtkAboutDialog.sgml		\
@@ -157,6 +158,7 @@ content_files =					\
 expand_content_files = 				\
 	drawing-model.xml			\
 	glossary.xml				\
+	migrating-2to3.xml			\
 	migrating-checklist.sgml		\
         migrating-ClientSideWindows.sgml	\
 	migrating-GtkAction.sgml		\
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 24595fa4f9..bb2b630dc2 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -400,6 +400,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
       </para>
     </partintro>
 
+    <xi:include href="migrating-2to3.xml" />
     <xi:include href="xml/migrating-checklist.sgml" />
     <xi:include href="changes-1.2.sgml" />
     <xi:include href="changes-2.0.sgml" />
diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml
new file mode 100644
index 0000000000..7ef2b3c277
--- /dev/null
+++ b/docs/reference/gtk/migrating-2to3.xml
@@ -0,0 +1,69 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<chapter id="gtk-migrating-2-to-3">
+  <title>Migrating from 2.x to 3.x</title>
+
+  <refsect1>
+  <title>Only single includes</title>
+  <para>
+    Make sure your program only include the toplevel headers:
+    <programlisting>
+    make CFLAGS+="-DG_DISABLE_SINGLE_INCLUDES -DGDK_PIXBUF_DISABLE_SINGLE_INCLUDES -DGTK_DISABLE_SINGLE_INCLUDES"
+    </programlisting>
+  </para>
+  </refsect1>
+
+  <refsect1>
+  <title>Do not use deprecated symbols</title>
+  <para>
+    Make sure your program doesn't use any deprecated functions:
+    <programlisting>
+    make CFLAGS+="-DG_DISABLE_DEPRECATED -DGDK_PIXBUF_DISABLE_DEPRECATED -DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
+    </programlisting>
+  </para>
+  </refsect1>
+
+  <refsect1>
+  <title>Use accessor funcions instead direc access</title>
+  <para>
+    GTK+ 3 removed many implementation details and struct members from
+    its public headers. To ensure that your application will not have problems
+    with this, you can define the preprocessor symbol GSEAL_ENABLE. This will
+    make the compiler catch all uses of direct access to struct fields so that
+    you can go through them one by one and replace them with a call to an
+    accessor function instead.
+    <programlisting>
+    make CFLAGS+="-DGSEAL_ENABLE"
+    </programlisting>
+  </para>
+  </refsect1>
+
+  <refsect1>
+  <title>GTK+ Modules</title>
+  <para>
+    Some GNOME modules install GTK+ modules. Since GTK+ 3 will be
+    parallel-installable with GTK+ 2.x, the two have separate locations for
+    their loadable modules. The location for GTK+ 2.x is $libdir/gtk-2.0
+    (and its subdirectories), for GTK+ 3, the location is $libdir/gtk-3.0
+    (and its subdirectories).
+  </para>
+  <para>
+    For some kinds of modules, namely im modules and pixbuf loaders,
+    GTK+ keeps a cache file with extra information about the modules.
+    These cache files are located in $sysconfdir/gtk-2.0 for GTK+ 2.x.
+    For GTK+ 3, they have been moved to $libdir/gtk-3.0/3.0.0/.
+    The commands that create these cache files have been renamed with a -3
+    suffix to make them parallel-installable.
+  </para>
+  <para>
+    Note that GTK+ modules often link against libgtk, libgdk-pixbuf, etc.
+    If that is the case for your module, you have to be careful to link the
+    GTK+ 2.x version of your module against the 2.x version of the libraries,
+    and the GTK+ 3 version against hte 3.x versions. Loading a module linked
+    against libgtk 2.x into an application using GTK+ 3 will lead to
+    unhappiness and must be avoided.
+  </para>
+  </refsect1>
+</chapter>