Basic explanation of 59692 (#534)

Author: noughtmare

message-index/messages/GHC-59692/example1/after/Example1.hs

@@ -0,0 +1,6 @@
+module Example1 where
+
+data T a
+
+instance Eq a => Eq (T a) where
+  (==) = (==)

message-index/messages/GHC-59692/example1/before/Example1.hs

@@ -0,0 +1,9 @@
+module Example1 where
+
+data T a
+
+instance Eq a => Eq (T a) where
+  (==) = (==)
+
+instance Show a => Eq (T a) where
+  (==) = (==)

message-index/messages/GHC-59692/example1/index.md

@@ -0,0 +1,19 @@
+---
+title: Identical Instance Heads
+---
+
+Even though the instances have different constraints, they are still considered the same.
+
+## Error message
+
+```
+messages/GHC-59692/example1/before/Example1.hs:3:10: error: [GHC-59692]
+    Duplicate instance declarations:
+      instance Eq a => Eq (T a)
+        -- Defined at messages/GHC-59692/example1/before/Example1.hs:3:10
+      instance Show a => Eq (T a)
+        -- Defined at messages/GHC-59692/example1/before/Example1.hs:6:10
+  |
+3 | instance Eq a => Eq (T a) where
+  |          ^^^^^^^^^^^^^^^^
+```

message-index/messages/GHC-59692/index.md

@@ -1,11 +1,15 @@
 ---
 title: Duplicate Instances
 summary: Multiple instances defined for the same type class and type.
-severity: error
 introduced: 9.6.1
+severity: error
 ---
 
-For type class coherence, at most one instance may be defined for each type for the same type class.
+You can only define a single instance for every type, because it must be possible to automatically resolve class constraints without any ambiguity.
+
+If the instances are identical, you should simply remove one.
+If you want multiple instances for the same type, you can circumvent this restriction by introducing a `newtype` wrapper. An example of this is shown in the solution for the "Multiple Instances for Semigroup Int" example.
+
+Note that instances are considered the same even if they have different constraints. Only the arguments of the class are considered when matching instances. This issue is shown in the "Identical Instance Heads" example.
 
-Identical instances should simply be removed.
-If multiple instances for the same type are required, circumventing this restriction is possible by introducing a `newtype` wrapper.
+See the [GHC User Guide](https://downloads.haskell.org/~ghc/9.12.1/docs/users_guide/exts/instances.html) for more information on instance declarations and resolution.