diff --git a/README.txt b/README.txt
index d4e4ed2..e0838ee 100644
--- a/README.txt
+++ b/README.txt
@@ -88,6 +88,100 @@ extensions.
   mapping.
 
 
+-- IMAGEMAGICK AND DRUPAL'S IMAGE API REVEALED --
+
+ImageMagick is a command line based image manipulation tool. It is executed
+through calls to the operating system shell, rather than using PHP functions.
+For this reason, the way the ImageMagick toolkit operates is very different
+from, for example, the GD toolkit provided by Drupal core.
+All the image manipulation performed by the operations provided by the Image
+API (scale, resize, desaturate, etc.), in fact, have to be accumulated and
+deferred to a single call of the 'convert' executable.
+The way ImageMagick toolkit interacts with Drupal Image API is the following:
+a) When an Image object is created, the toolkit calls ImageMagick's 'identify'
+   command to retrieve information about the image itself (e.g. format, width,
+   height, orientation).
+b) When operations are applied to the Image object (typically as part of
+   creating an image style derivative), the toolkit *both* adds arguments to
+   the command line to be executed *and* keeps track of the changes occurring
+   to the width/height/orientation. It does so based purely on the information
+   retrieved sub (a), and the expected changes introduced by a specific
+   operation, because we do not have an object in memory that can be tested
+   against current values as we have in the GD toolkit.
+c) When the Image object is 'saved' (typically at the end of the image style
+   derivative creatione process), then the toolkit actually executes
+   ImageMagick's 'convert' command with the entire set of arguments that have
+   been added by effects/operations so far.
+
+
+-- DEBUGGING IMAGEMAGICK COMMANDS --
+
+The toolkit provides some of options to facilitate debugging the execution of
+ImageMagick commands.
+
+- Display debugging information
+
+  Go to Administration » Configuration » Media » Image toolkit and select the
+  'Display debugging information' tickbox in the 'Execution options' box. This
+  will result in logging all the parameters passed in input to the 'identify'
+  and 'convert' binaries, and all output/errors produced by the execution. The
+  same information will also be presented interactively to users with the
+  'Administer site configuration' permission. These entries can be for example
+  used to call the commands in a shell window.
+
+  As an example, the following is logged when an image derivative is generated
+  by the 'Thumbnail' image style:
+
+   ImageMagick command: identify -format 'format:%m|width:%w|height:%h|exif_orientation:%[EXIF:Orientation]' 'core/modules/image/sample.png'
+   ImageMagick output:  format:PNG|width:800|height:600|exif_orientation:
+   ImageMagick command: convert 'core/modules/image/sample.png' -resize 100x75! -quality 75 '/[...]/sites/default/files/styles/thumbnail/public/core/modules/image/sample.png'
+   ImageMagick command: identify -format 'format:%m|width:%w|height:%h|exif_orientation:%[EXIF:Orientation]' '/[...]/sites/default/files/styles/thumbnail/public/core/modules/image/sample.png'
+   ImageMagick output:  format:PNG|width:100|height:75|exif_orientation:
+
+- Prepend -debug argument
+
+  Go to Administration » Configuration » Media » Image toolkit and enter, for
+  example, '-debug All' in the 'Prepend arguments' text box. Also, enable
+  'Display debugging information' as described above. This will instruct
+  ImageMagick 'identify' and 'convert' binaries to produce a verbose log of
+  their internal operations execution, that can be checked in case of issues.
+  Also, a '-log' argument can be entered to specify how to format the log
+  itself.
+  For more details, see ImageMagick documentation online:
+    https://www.imagemagick.org/script/command-line-options.php#debug
+    https://www.imagemagick.org/script/command-line-options.php#log
+
+  This requires some trials before getting the required level of detail. A good
+  combination is "-debug All -log '%u: %d - %e'". Following on the example
+  above, this will log something like (extract):
+
+   ImageMagick command: convert 'core/modules/image/sample.png' -debug All -log '%u: %d - %e' -resize 100x75! -quality 75 '/[...]/sites/default/files/styles/thumbnail/public/core/modules/image/sample.png'
+   ImageMagick error:
+      [...]
+      0.110u: Cache - destroy core/modules/image/sample.png[0]
+      0.110u: Resource - Memory: 3.84MB/58.6KiB/25.46GiB
+      0.110u: Policy - Domain: Coder; rights=Write; pattern="PNG" ...
+      0.110u: Coder - Enter WritePNGImage()
+      0.110u: Coder -   Enter WriteOnePNGImage()
+      0.110u: Coder -     storage_class=DirectClass
+      0.110u: Coder -     Enter BUILD_PALETTE:
+      0.110u: Coder -       image->columns=100
+      0.110u: Coder -       image->rows=75
+      0.110u: Coder -       image->matte=0
+      0.110u: Coder -       image->depth=8
+      0.110u: Coder -       image->colors=0
+      0.110u: Coder -         (zero means unknown)
+      0.110u: Coder -       Regenerate the colormap
+      0.110u: Coder -       Check colormap for background (65535,65535,65535)
+      0.110u: Coder -       No room in the colormap to add background color
+      0.110u: Coder -       image has more than 256 colors
+      0.110u: Coder -       image->colors=0
+      0.110u: Coder -       number_transparent     = 0
+      0.110u: Coder -       number_opaque          > 256
+      0.110u: Coder -       number_semitransparent = 0
+      [...]
+
+
 -- CONTACT --
 
 Current maintainers: