       3
 
   Tuples being stored contiguously in memory also means that updating a tuple
-  (for example replacing an element with `Kernel.put_elem/3`) will make a copy
-  of the whole tuple.
+  (for example replacing an element with `Kernel.put_elem/3`) will make a
+  shallow copy of the whole tuple. The tuple elements are still shared thanks
+  to immutability.
 
-  Tuples are not meant to be used as a "collection" type (which is also
-  suggested by the absence of an implementation of the `Enumerable` protocol for
-  tuples): they're mostly meant to be used as a fixed-size container for
-  multiple elements. For example, tuples are often used to have functions return
-  "enriched" values: a common pattern is for functions to return `{:ok, value}`
-  for successful cases and `{:error, reason}` for unsuccessful cases. For
-  example, this is exactly what `File.read/1` does: it returns `{:ok, contents}`
-  if reading the given file is successful, or `{:error, reason}` otherwise
-  (e.g., `{:error, :enoent}` if the file doesn't exist).
+  Tuples are not meant to be used as a "collection" type but rather as a
+  fixed-size container for multiple elements. That's why it is not possible
+  to traverse a tuple dynamically using the functions in the `Enum` module.
 
-  This module provides functions to work with tuples; some more functions to
-  work with tuples can be found in `Kernel` (`Kernel.tuple_size/1`,
-  `Kernel.elem/2`, `Kernel.put_elem/3`, and others).
+  For example, tuples are often used to have functions return "enriched"
+  values: a common pattern is for functions to return `{:ok, value}` for
+  successful cases and `{:error, reason}` for unsuccessful cases. This is
+  exactly what `File.read/1` does: it returns `{:ok, contents}` if reading
+  the given file is successful, or `{:error, reason}` otherwise, such as
+  when the file does not exist.
+
+  The most common operations performed on tuples are available in `Kernel`
+  (`Kernel.tuple_size/1`, `Kernel.elem/2`, `Kernel.put_elem/3`, and others)
+  and are automatically imported into your code. The functions in this module
+  cover other cases, such as dynamic creation of tuples (`Tuple.duplicate/2`)
+  and conversion to list (`Tuple.to_list/1`). The functions that add and remove
+  elements from tuples, changing their size, are rarely used in practice, as
+  they typically imply tuples are being used as collections. Even if you have
+  a tuple `{:ok, atom}` and you want to append another element to it, such as
+  an empty map, it is preferrable to rely on pattern matching and create a new
+  tuple than manipulating it dynamically:
+
+      tuple = {:ok, :example}
+
+      # Avoid
+      Tuple.insert_at(tuple, 2, %{}}
+
+      # Prefer
+      {:ok, atom} = tuple
+      {:ok, atom, %{}}
+
   """
 
   @doc """

  @moduledoc """
  Functions for working with tuples.

  Tuples are ordered collections of elements; tuples can contain elements of any
  type, and a tuple can contain elements of different types. Curly braces can be
  used to create tuples:

      iex> {}
      {}
      iex> {1, :two, "three"}
      {1, :two, "three"}

  Tuples store elements contiguously in memory; this means that accessing a
  tuple element by index (which can be done through the `Kernel.elem/2`
  function) is a constant-time operation:

      iex> tuple = {1, :two, "three"}
      iex> elem(tuple, 0)

      iex> elem(tuple, 2)
      "three"

  Same goes for getting the tuple size with `Kernel.tuple_size/1`:

      iex> tuple_size({})
      0
