diff --git a/core/modules/migrate/migrate.api.php b/core/modules/migrate/migrate.api.php
index c89614e..2a2610b 100644
--- a/core/modules/migrate/migrate.api.php
+++ b/core/modules/migrate/migrate.api.php
@@ -1,12 +1,114 @@
 <?php
 
+/**
+ * @file
+ * Hooks provided by the Migrate module.
+ */
+
 use Drupal\migrate\Entity\MigrationInterface;
 use Drupal\migrate\Plugin\MigrateSourceInterface;
 use Drupal\migrate\Row;
 
 /**
- * @file
- * Hooks provided by the Migrate module.
+ * @defgroup migration Migration API
+ * @{
+ * Overview of the Migration API, which migrates data into Drupal.
+ *
+ * @section overview Overview of migration
+ * Migration is an
+ * @link http://wikipedia.org/wiki/Extract,_transform,_load Extract, Transform, Load @endlink
+ * (ETL) process. For historical reasons, in the Drupal migration tool the
+ * extract phase is called "source", the transform phase is called "process",
+ * and the load phase is called "destination".
+ *
+ * Source, process, and destination phases are each provided by plugins. Source
+ * plugins extract data from a data source in "rows". Each row of data is handed
+ * off to a series of process plugins, which transform the data if necessary
+ * (setting default values, mapping values, etc.). The resulting row is handed
+ * off to a destination plugin, which saves the data as some sort of Drupal
+ * object (configuration, entity, URL alias, etc.). In setting up a generic
+ * migration, the destination may not be completely known; a common example
+ * of this is in migrating entities with fields. In this case, there is a
+ * load plugin involved, which has the responsibility of loading and setting up
+ * the destination.
+ *
+ * The Migrate module provides process plugins for common operations, and
+ * destination plugins for Drupal core objects. The Migrate Drupal module
+ * provides source plugins to extract data from various versions of Drupal, and
+ * load plugins for dealing with various entities and fields. Custom and
+ * contributed modules can provide additional plugins; see the
+ * @link plugin_api Plugin API topic @endlink for generic information about
+ * providing plugins, and sections below for details about the plugin types.
+ *
+ * The configuration of migrations is stored in configuration entities, which
+ * list the IDs and configurations of the plugins that are involved. See
+ * @ref sec_entity below for details. To migrate an entire site, you'll need to
+ * create a migration manifest; see @ref sec_manifest for details.
+ *
+ * https://drupal.org/node/2127611 has more complete information on the
+ * Migration API.
+ *
+ * @section sec_source Source plugins
+ * Migration source plugins implement
+ * \Drupal\migrate\Plugin\MigrateSourceInterface and usually extend
+ * \Drupal\migrate\Plugin\migrate\source\SourcePluginBase. They are annotated
+ * with \Drupal\migrate\Annotation\MigrateSource annotation, and must be in
+ * namespace subdirectory Plugin\migrate\source under the namespace of the
+ * module that defines them. Migration source plugins are managed by the
+ * \Drupal\migrate\Plugin\MigratePluginManager class.
+ *
+ * @section sec_process Process plugins
+ * Migration process plugins implement
+ * \Drupal\migrate\Plugin\MigrateProcessInterface and usually extend
+ * \Drupal\migrate\ProcessPluginBase. They are annotated
+ * with \Drupal\migrate\Annotation\MigrateProcessPlugin annotation, and must be
+ * in namespace subdirectory Plugin\migrate\process under the namespace of the
+ * module that defines them. Migration process plugins are managed by the
+ * \Drupal\migrate\Plugin\MigratePluginManager class.
+ *
+ * @section sec_destination Destination plugins
+ * Migration destination plugins implement
+ * \Drupal\migrate\Plugin\MigrateDestinationInterface and usually extend
+ * \Drupal\migrate\Plugin\migrate\destination\DestinationBase. They are
+ * annotated with \Drupal\migrate\Annotation\MigrateDestination annotation, and
+ * must be in namespace subdirectory Plugin\migrate\destination under the
+ * namespace of the module that defines them. Migration destination plugins
+ * are managed by the
+ * \Drupal\migrate\Plugin\MigrateDestinationPluginManager class.
+ *
+ * @section sec_load Load plugins
+ * Migration load plugins implement
+ * \Drupal\migrate_drupal\Plugin\MigrateLoadInterface, and generally extend
+ * \Drupal\migrate_drupal\Plugin\migrate\load\LoadEntity. Their only annotation
+ * is a generic PluginID annotation, and they must be in namespace subdirectory
+ * Plugin\migrate\load under the namespace that defines them. Migration load
+ * plugins are managed by the \Drupal\migrate\Plugin\MigratePluginManager class.
+ *
+ * @section sec_entity Migration configuration entities
+ * The definition of how to migrate each type of data is stored in configuration
+ * entities. The migration configuration entity class is
+ * \Drupal\migrate\Entity\Migration, with interface
+ * \Drupal\migrate\Entity\MigrationEntity; the configuration schema can be found
+ * in the migrate.schema.yml file. Migration configuration consists of IDs and
+ * configuration for the source, process, load (if needed), and destination
+ * plugins, as well as information on dependencies. You can find examples of
+ * migration configuration files in the
+ * core/modules/migrate_drupal/config/install directory.
+ *
+ * @section sec_manifest Migration manifests
+ * You can run a migration with the "drush migrate-manifest" command, providing
+ * a migration manifest file. This file lists the configuration names of the
+ * migrations you want to execute, as well as any dependencies they have (you
+ * can find these in the "migration_dependencies" sections of the individual
+ * configuration files). For example, to migrate blocks from a Drupal 6 site,
+ * you would list:
+ * @code
+ * # Migrate blocks from Drupal 6 to 8
+ * - d6_filter_format
+ * - d6_custom_block
+ * - d6_block
+ * @endcode
+ * @}
  */
 
 /**
@@ -21,7 +123,9 @@
  * variables table which now needs to be inside the filter format config
  * file. So, it needs to be added here.
  *
- * hook_migrate_MIGRATION_ID_prepare_row is also available.
+ * hook_migrate_MIGRATION_ID_prepare_row() is also available.
+ *
+ * @ingroup migration
  */
 function hook_migrate_prepare_row(Row $row, MigrateSourceInterface $source, MigrationInterface $migration) {
   if ($migration->id() == 'd6_filter_formats') {
diff --git a/core/modules/migrate/src/Annotation/MigrateDestination.php b/core/modules/migrate/src/Annotation/MigrateDestination.php
index f7686f9..3837370 100644
--- a/core/modules/migrate/src/Annotation/MigrateDestination.php
+++ b/core/modules/migrate/src/Annotation/MigrateDestination.php
@@ -24,6 +24,8 @@
  * @see \Drupal\migrate\Annotation\MigrateProcessPlugin
  * @see plugin_api
  *
+ * @ingroup migration
+ *
  * @Annotation
  */
 class MigrateDestination extends Plugin {
diff --git a/core/modules/migrate/src/Annotation/MigrateProcessPlugin.php b/core/modules/migrate/src/Annotation/MigrateProcessPlugin.php
index 5aa1323..d01eb7d 100644
--- a/core/modules/migrate/src/Annotation/MigrateProcessPlugin.php
+++ b/core/modules/migrate/src/Annotation/MigrateProcessPlugin.php
@@ -19,11 +19,13 @@
  *
  * @see \Drupal\migrate\Plugin\MigratePluginManager
  * @see \Drupal\migrate\Plugin\MigrateProcessInterface
- * @see \Drupal\migrate\Plugin\migrate\process\ProcessPluginBase
+ * @see \Drupal\migrate\ProcessPluginBase
  * @see \Drupal\migrate\Annotation\MigrateSource
  * @see \Drupal\migrate\Annotation\MigrateDestination
  * @see plugin_api
  *
+ * @ingroup migration
+ *
  * @Annotation
  */
 class MigrateProcessPlugin extends Plugin {
diff --git a/core/modules/migrate/src/Annotation/MigrateSource.php b/core/modules/migrate/src/Annotation/MigrateSource.php
index 9093d7f..08957a3 100644
--- a/core/modules/migrate/src/Annotation/MigrateSource.php
+++ b/core/modules/migrate/src/Annotation/MigrateSource.php
@@ -25,6 +25,8 @@
  * @see \Drupal\migrate\Annotation\MigrateDestination
  * @see plugin_api
  *
+ * @ingroup migration
+ *
  * @Annotation
  */
 class MigrateSource extends Plugin {
diff --git a/core/modules/migrate/src/Plugin/MigrateDestinationInterface.php b/core/modules/migrate/src/Plugin/MigrateDestinationInterface.php
index a238dbd..50f2a9b 100644
--- a/core/modules/migrate/src/Plugin/MigrateDestinationInterface.php
+++ b/core/modules/migrate/src/Plugin/MigrateDestinationInterface.php
@@ -19,6 +19,8 @@
  * @see \Drupal\migrate\Plugin\MigrateDestinationPluginManager
  * @see \Drupal\migrate\Annotation\MigrateDestination
  * @see plugin_api
+ *
+ * @ingroup migration
  */
 interface MigrateDestinationInterface extends PluginInspectionInterface {
 
diff --git a/core/modules/migrate/src/Plugin/MigrateDestinationPluginManager.php b/core/modules/migrate/src/Plugin/MigrateDestinationPluginManager.php
index 2b731af..b8f187d 100644
--- a/core/modules/migrate/src/Plugin/MigrateDestinationPluginManager.php
+++ b/core/modules/migrate/src/Plugin/MigrateDestinationPluginManager.php
@@ -20,6 +20,8 @@
  * @see \Drupal\migrate\Plugin\destination\DestinationBase
  * @see \Drupal\migrate\Annotation\MigrateDestination
  * @see plugin_api
+ *
+ * @ingroup migration
  */
 class MigrateDestinationPluginManager extends MigratePluginManager {
 
diff --git a/core/modules/migrate/src/Plugin/MigratePluginManager.php b/core/modules/migrate/src/Plugin/MigratePluginManager.php
index 0dc52c5..0ae77be 100644
--- a/core/modules/migrate/src/Plugin/MigratePluginManager.php
+++ b/core/modules/migrate/src/Plugin/MigratePluginManager.php
@@ -24,6 +24,8 @@
  * @see \Drupal\migrate\Plugin\MigrateProcessInterface
  * @see \Drupal\migrate\Plugin\migrate\process\ProcessPluginBase
  * @see plugin_api
+ *
+ * @ingroup migration
  */
 class MigratePluginManager extends DefaultPluginManager {
 
diff --git a/core/modules/migrate/src/Plugin/MigrateProcessInterface.php b/core/modules/migrate/src/Plugin/MigrateProcessInterface.php
index d050475..724f275 100644
--- a/core/modules/migrate/src/Plugin/MigrateProcessInterface.php
+++ b/core/modules/migrate/src/Plugin/MigrateProcessInterface.php
@@ -15,9 +15,11 @@
  * An interface for migrate process plugins.
  *
  * @see \Drupal\migrate\Plugin\MigratePluginManager
- * @see \Drupal\migrate\Plugin\migrate\process\ProcessPluginBase
+ * @see \Drupal\migrate\ProcessPluginBase
  * @see \Drupal\migrate\Annotation\MigrateProcessPlugin
  * @see plugin_api
+ *
+ * @ingroup migration
  */
 interface MigrateProcessInterface extends PluginInspectionInterface {
 
diff --git a/core/modules/migrate/src/Plugin/MigrateSourceInterface.php b/core/modules/migrate/src/Plugin/MigrateSourceInterface.php
index 19dc37a..5ff3f98 100644
--- a/core/modules/migrate/src/Plugin/MigrateSourceInterface.php
+++ b/core/modules/migrate/src/Plugin/MigrateSourceInterface.php
@@ -16,6 +16,8 @@
  * @see \Drupal\migrate\Annotation\MigrateSource
  * @see \Drupal\migrate\Plugin\migrate\source\SourcePluginBase
  * @see plugin_api
+ *
+ * @ingroup migration
  */
 interface MigrateSourceInterface extends \Countable, PluginInspectionInterface {
 
diff --git a/core/modules/migrate/src/Plugin/migrate/destination/DestinationBase.php b/core/modules/migrate/src/Plugin/migrate/destination/DestinationBase.php
index fa5a3ef..6fd3e97 100644
--- a/core/modules/migrate/src/Plugin/migrate/destination/DestinationBase.php
+++ b/core/modules/migrate/src/Plugin/migrate/destination/DestinationBase.php
@@ -20,6 +20,8 @@
  * @see \Drupal\migrate\Plugin\MigrateDestinationPluginManager
  * @see \Drupal\migrate\Annotation\MigrateDestination
  * @see plugin_api
+ *
+ * @ingroup migration
  */
 abstract class DestinationBase extends PluginBase implements MigrateDestinationInterface, RequirementsInterface {
 
diff --git a/core/modules/migrate/src/Plugin/migrate/source/SourcePluginBase.php b/core/modules/migrate/src/Plugin/migrate/source/SourcePluginBase.php
index aa85ace..1d1fa6c 100644
--- a/core/modules/migrate/src/Plugin/migrate/source/SourcePluginBase.php
+++ b/core/modules/migrate/src/Plugin/migrate/source/SourcePluginBase.php
@@ -19,6 +19,8 @@
  * @see \Drupal\migrate\Annotation\MigrateSource
  * @see \Drupal\migrate\Plugin\MigrateSourceInterface
  * @see plugin_api
+ *
+ * @ingroup migration
  */
 abstract class SourcePluginBase extends PluginBase implements MigrateSourceInterface  {
 
diff --git a/core/modules/migrate/src/ProcessPluginBase.php b/core/modules/migrate/src/ProcessPluginBase.php
index 71440b0..f5652a1 100644
--- a/core/modules/migrate/src/ProcessPluginBase.php
+++ b/core/modules/migrate/src/ProcessPluginBase.php
@@ -22,6 +22,8 @@
  * @see \Drupal\migrate\Plugin\MigrateProcessInterface
  * @see \Drupal\migrate\Annotation\MigrateProcessPlugin
  * @see plugin_api
+ *
+ * @ingroup migration
  */
 abstract class ProcessPluginBase extends PluginBase implements MigrateProcessInterface {
 
diff --git a/core/modules/migrate_drupal/src/Plugin/MigrateLoadInterface.php b/core/modules/migrate_drupal/src/Plugin/MigrateLoadInterface.php
index 2d7a263..34dd07b 100644
--- a/core/modules/migrate_drupal/src/Plugin/MigrateLoadInterface.php
+++ b/core/modules/migrate_drupal/src/Plugin/MigrateLoadInterface.php
@@ -9,6 +9,13 @@
 
 use Drupal\Core\Entity\EntityStorageInterface;
 
+/**
+ * Defines an interface for migration load plugins.
+ *
+ * @see \Drupal\migrate_drupal\Plugin\migrate\load\LoadEntity
+ *
+ * @ingroup migration
+ */
 interface MigrateLoadInterface {
 
   /**
diff --git a/core/modules/migrate_drupal/src/Plugin/migrate/load/LoadEntity.php b/core/modules/migrate_drupal/src/Plugin/migrate/load/LoadEntity.php
index a45baac..d112a11 100644
--- a/core/modules/migrate_drupal/src/Plugin/migrate/load/LoadEntity.php
+++ b/core/modules/migrate_drupal/src/Plugin/migrate/load/LoadEntity.php
@@ -18,6 +18,8 @@
 /**
  * Base class for entity load plugins.
  *
+ * @ingroup migration
+ *
  * @PluginID("drupal_entity")
  */
 class LoadEntity extends PluginBase implements MigrateLoadInterface {
diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 89ac0c8..a2e2327 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -851,20 +851,6 @@
  */
 
 /**
- * @defgroup migration Migration API
- * @{
- * Overview of the Migration API, which migrates data into Drupal.
- *
- * @todo write this
- *
- * Additional documentation paragraphs need to be written, and functions,
- * classes, and interfaces need to be added to this topic.
- *
- * See https://drupal.org/node/2127611
- * @}
- */
-
-/**
  * @defgroup testing Automated tests
  * @{
  * Overview of PHPUnit tests and Simpletest tests.