Merge pull request #1756 from LukaJCB/piecemeal-import-guide

Add piecemeal import guide

docs/src/main/tut/typeclasses/imports.md

@@ -40,4 +40,40 @@ val o: Option[String] = None
 o.orEmpty
 ```
 
-**Note**: if you import `cats.implicits._` (the preferred method), you should _not_ also use imports like `cats.syntax.option._` or `cats.instances.either._`. This can result in ambiguous implicit values that cause bewildering compile errors.
+If you'd like to import à la carte, you can do so, by importing from `cats.instances` for the type class instances and `cats.syntax` for syntax enrichment.
+For example, if you'd like to import the `Monoid` instance for `String` and the corresponding syntax:
+```tut:book
+import cats.instances.string._
+import cats.syntax.monoid._
+
+"Hello, " |+| "World!"
+```
+The first import pulls the `Semigroup` instance for String into the scope, while the second import adds the `|+|` syntax.
+
+You can also import all syntax or all instances by importing `cats.syntax.all._` or `cats.instances.all._` respectively.
+
+For data types included in cats (i.e. data structure from the `cats.data` package), all type class instances are bundled with their implementation and therefore do not need to be imported separately.
+For example, if we wanted to import `NonEmptyList` from the `cats.data` package and use it's `SemigroupK` instance, we would not need to specifically import the instance:
+
+```tut:book
+import cats.data.NonEmptyList
+import cats.syntax.semigroupk._
+
+NonEmptyList.of(1,2) <+> NonEmptyList.of(3,4)
+```
+
+
+**Note**: Beware that if you import a type class instance or its syntax twice, you will receive conflicting implicits with a less than helpful error message.
+This usually happens when importing different type classes in the same hierarchy or when importing syntax enrichment for all type classes using `cats.syntax.all._` or `cats.implicits._` together with a more specific import like `cats.syntax.option._` or `cats.instances.either._`.
+Below is an example of this phenomenon:
+```tut:silent
+import cats.instances.all._
+import cats.syntax.semigroup._
+val x = -2 |+| 1
+
+//now we also need access to isEmpty from Monoid
+import cats.syntax.monoid._
+(x |+| 1).isEmpty //error: value |+| is not a member of Int
+```
+
+Compilation fails on the second invocation of `|+|` because we now have conflicting implicits from `Monoid` and `Semigroup`.