diff --git a/core/modules/media/src/MediaHandlerInterface.php b/core/modules/media/src/MediaHandlerInterface.php
index 4afafce5c9..c8f6613861 100644
--- a/core/modules/media/src/MediaHandlerInterface.php
+++ b/core/modules/media/src/MediaHandlerInterface.php
@@ -9,21 +9,49 @@
 /**
  * Defines the interface for media handler plugins.
  *
- * Media handlers are the essential part of the media entity type as they
- * implement the knowledge and business logic related to a given sort of media.
- * Media entity doesn't have any knowledge anything about media it represents
- * without handlers.
+ * Media handlers are the essential part of the media type as they implement the
+ * knowledge and business logic related to a given sort of media. Media entity,
+ * without a handler, doesn't have any knowledge about media it represents.
  *
- * Each Media type needs exactly one handler and a single handler can be used on
+ * Each Media type needs exactly one handler. A single handler can be used on
  * many media types.
  *
- * Their main responsibilities are:
- * - defining how media is represented (stored),
- * - providing thumbnails,
- * - validating media before it is saved,
- * - providing default value for the media name field,
- * - providing metadata specific to the given media,
- * - handling mapping between metadata and entity fields.
+ * Examples of possible handlers are:
+ * - File: handles local files,
+ * - Image: handles local images,
+ * - oEmbed: handles resources that are exposed through the oEmbed standard,
+ * - YouTube: handles YouTube videos,
+ * - SoundCould: handles SoundCould audio,
+ * - Instagram: handles Instagram posts,
+ * - Twitter: handles Tweets,
+ * - ...
+ *
+ * Their responsibilities are:
+ * - Defining how media is represented (stored). Handlers are not responsible to
+ *   actually store the media. They only define how it is represented on a media
+ *   entity (usually using some kind of a field).
+ * - Providing thumbnails. Handlers that are responsible for remote media will
+ *   generally fetch the image from the 3rd party API and make it available for
+ *   the local usage. Handlers that represent local resources (such as images)
+ *   will usually use some locally provided image. Both will also fall back to
+ *   a pre-defined default thumbnail if everything else fails.
+ * - Validating a media entity before it is saved. Entity constraint system will
+ *   be used to ensure the valid structure of the media entity. Handlers that
+ *   represent remote media will usually ensure that the URL or and other
+ *   identifier is correct. Handlers that are responsible for local files could
+ *   ensure the mime type of the file is correct or something along those lines.
+ * - Providing a default value for the media name field. This will save users
+ *   from manually entering the name where it can be reliably set automatically.
+ *   Handlers for local files will generally use filename. Handlers for remote
+ *   resources might use something like a video/photo title or something similar
+ *   to that. Name can be always overridden by the user.
+ * - Providing metadata specific to the given media type. Remote media handlers
+ *   will generally get information available through the 3rd party API and make
+ *   it available to Drupal. Local media handlers can expose things such as EXIF
+ *   or ID3.
+ * - Handling mapping metadata to the media entity fields. Metadata that handler
+ *   exposes can be automatically mapped to the fields on the media entity.
+ *   Handler will be able to define how this is done.
  *
  * @see \Drupal\media\Annotation\MediaHandler
  * @see \Drupal\media\MediaHandlerBase
diff --git a/core/modules/media/src/MediaTypeInterface.php b/core/modules/media/src/MediaTypeInterface.php
index 311d0f4e70..071440b7ba 100644
--- a/core/modules/media/src/MediaTypeInterface.php
+++ b/core/modules/media/src/MediaTypeInterface.php
@@ -10,13 +10,23 @@
  * Provides an interface defining a media type entity.
  *
  * Media types are bundles for the media entity. They are used to group media
- * with same semantics. Media types are not about where media comes from. They
- * are about the meaning that media has in context of a given Drupal site.
+ * with the same semantics. Media types are not about where media comes from.
+ * They are about the semantics that media has in the context of a given Drupal
+ * site.
  *
  * Media handlers, on the other hand, are aware where media comes from and know
  * how to represent and handle it in Drupal's context. They are aware of the low
- * level details, while types don't care about them at all. That said, media
- * types can not exist without handlers.
+ * level details, while the media types don't care about them at all. That said,
+ * media types can not exist without handlers.
+ *
+ * Consider the following examples:
+ * - oEmbed media handler which can represent any oEmbed resource. Media types
+ *   that could be used with this handler are "Videos", "Charts", "Music", etc.
+ *   All of them are retrieved using the same protocol, but they represent very
+ *   different things.
+ * - Handler that represents files could be used with media types like
+ *   "Invoices", "Subtitles", "Meeting notes", etc. They are all files stored on
+ *   some kind of storage, but their meaning is different.
  *
  * @see \Drupal\media\MediaHandlerInterface
  */