diff --git a/docs/datamodel/index.rst b/docs/datamodel/index.rst
index afc7393ddb0..0dc7824db4d 100644
--- a/docs/datamodel/index.rst
+++ b/docs/datamodel/index.rst
@@ -76,8 +76,8 @@ Example:
   `Atom <https://atom.io/packages/edgedb>`_, and `Vim <https://github.com/
   geldata/edgedb-vim>`_.
 
-Migrations
-----------
+Migrations and DDL
+------------------
 
 Gel's baked-in migration system lets you painlessly evolve your schema over
 time. Just update the contents of your |.gel| file(s) and use the |Gel| CLI
@@ -90,6 +90,11 @@ to *create* and *apply* migrations.
   $ gel migrate
   Applied dbschema/migrations/00001.edgeql
 
+Migrations are sequences of *data definition language* (DDL) commands.
+DDL is a low level language that tells the database how exactly to change
+the schema. Don't worry, you won't need to write any DDL directly, the Gel
+server will generate it for you.
+
 For a full guide on migrations, refer to the :ref:`Creating and applying
 migrations <ref_intro_migrations>` guide or the
 :ref:`migrations reference <ref_datamodel_migrations>` section.
diff --git a/docs/datamodel/migrations.rst b/docs/datamodel/migrations.rst
index 626c95923e3..9b941e8a536 100644
--- a/docs/datamodel/migrations.rst
+++ b/docs/datamodel/migrations.rst
@@ -77,6 +77,7 @@ For this use case you can use the :gelcmd:`watch` command, which will
 monitor your |.gel| files and automatically create and apply migrations
 for you in the background.
 
+.. _ref_eql_ddl:
 
 Data definition language (DDL)
 ==============================
@@ -84,6 +85,11 @@ Data definition language (DDL)
 The migration plan is a sequence of DDL commands. DDL commands are low-level
 instructions that describe the changes to the schema.
 
+SDL and your |.gel| files are like a 3D printer: you design the final shape,
+and the system puts a database together for you. Using DDL is like building a
+house the traditional way: to add a window, you first need a frame; to have a
+frame, you need a wall; and so on.
+
 If your schema looks like this:
 
 .. code-block:: sdl
diff --git a/docs/reference/ddl/index.rst b/docs/reference/ddl/index.rst
deleted file mode 100644
index 2f6dde9b488..00000000000
--- a/docs/reference/ddl/index.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-.. _ref_eql_ddl:
-
-DDL
-===
-
-:edb-alt-title: Data Definition Language
-
-EdgeQL includes a set of *data definition language* (DDL) commands that
-manipulate the database's schema. DDL is the low-level equivalent to
-:ref:`Gel schema definition language <ref_eql_sdl>`. You can execute DDL
-commands against your database, just like any other EdgeQL query.
-
-.. code-block:: edgeql-repl
-
-    gel> create type Person {
-    ....     create required property name -> str;
-    .... };
-    OK: CREATE TYPE
-    gel> create type Movie {
-    ....     create required property title -> str;
-    ....     create required link director -> Person;
-    .... };
-    OK: CREATE TYPE
-
-In DDL, the *order* of commands is important. In the example above, you
-couldn't create ``Movie`` before ``Person``, because ``Movie`` contains a link
-to ``Person``.
-
-Under the hood, all migrations are represented as DDL scripts: a sequence of
-imperative commands representing the migration. When you :ref:`create a
-migration <ref_cli_gel_migrate>` with the CLI, Gel produces a DDL script.
-
-
-Comparison to SDL
------------------
-
-SDL is sort of like a 3D printer: you design the final shape and it puts
-it together for you. DDL is like building a house with traditional
-methods: to add a window, you first need a frame, to have a frame you
-need a wall, and so on.
-
-DDL lets you make quick changes to your schema without creating migrations. But
-it can be dangerous too; some ``DDL`` commands can destroy user data
-permanantly. In practice, we recommend most users stick with SDL until they get
-comfortable, then start experimenting with DDL.
-
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 85b26488fa0..f7c57cb6ef1 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -13,7 +13,6 @@ Reference
 
 
     edgeql/index
-    ddl/index
     connection
     environment
     projects