[doc] Update docs

Author: ptaoussanis

README.md

@@ -9,7 +9,15 @@ Getting even the simplest Java logging working can be maddeningly complex, and i
 
 Timbre offers an **all Clojure/Script** alternative that's fast, deeply flexible, easy to configure with pure Clojure data, and that **just works out the box**.
 
-Supports optional interop with [tools.logging](https://github.com/taoensso/timbre/blob/master/src/taoensso/timbre/tools/logging.clj) and [log4j/logback/slf4j](https://github.com/fzakaria/slf4j-timbre).
+Supports optional interop with [tools.logging](../../wiki/4-Interop#toolslogging) and [Java logging via SLF4Jv2](../../wiki/4-Interop#java-logging).
+
+## Library status
+
+While I will continue to support Timbre as always, I'd recommend new users see [Telemere](https://www.taoensso.com/telemere) instead - which is essentially a **modern rewrite of Timbre**.
+
+There's **zero pressure** for existing users of Timbre to migrate, though there are significant benefits - and migration is often [quick and easy](https://github.com/taoensso/telemere/wiki/5-Migrating#from-timbre). See [here](https://github.com/taoensso/telemere/wiki/6-FAQ#why-not-just-update-timbre) for why I made the decision to release a new library.
+
+\- Peter Taoussanis
 
 ## Latest release/s
 

wiki/3-Community.md

@@ -14,10 +14,10 @@ GitHub PRs very welcome for:
 
 If you spot issues with any linked resources, please **contact the relevant authors** to let them know!
 
-Contributor | Link | Description
-:-- | :-- | :--
-[@fzakaria](https://github.com/fzakaria) | [slf4j-timbre](https://github.com/fzakaria/slf4j-timbre) | Route log4j/logback/sfl4j log output to Timbre
-[@palletops](https://github.com/palletops) | [log-config](https://github.com/palletops/log-config)  | Library to help manage Timbre logging config
-[@djblue](https://github.com/djblue) | [portal](https://github.com/djblue/portal/tree/master/examples/timbre) | Guide to using Timbre with [Portal](https://github.com/djblue/portal)
-[@viesti](https://github.com/viesti) | [timbre-json-appender](https://github.com/viesti/timbre-json-appender/) | JSON appender for Timbre
-_ | _ | Your link here? [PRs](../wiki#contributions-welcome) welcome!
+| Contributor                                | Link                                                                    | Description                                                                                                                         |
+| :----------------------------------------- | :---------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
+| [@fzakaria](https://github.com/fzakaria)   | [slf4j-timbre](https://github.com/fzakaria/slf4j-timbre)                | Route log4j/logback/sfl4j log output to Timbre (**UPDATE**: Timbre now includes [built-in SLF4J support](./4-Interop#java-logging)) |
+| [@palletops](https://github.com/palletops) | [log-config](https://github.com/palletops/log-config)                   | Library to help manage Timbre logging config                                                                                        |
+| [@djblue](https://github.com/djblue)       | [portal](https://github.com/djblue/portal/tree/master/examples/timbre)  | Guide to using Timbre with [Portal](https://github.com/djblue/portal)                                                               |
+| [@viesti](https://github.com/viesti)       | [timbre-json-appender](https://github.com/viesti/timbre-json-appender/) | JSON appender for Timbre                                                                                                            |
+| _                                          | _                                                                       | Your link here? [PRs](../wiki#contributions-welcome) welcome!                                                                       |

wiki/4-Interop.md

@@ -0,0 +1,29 @@
+# tools.logging
+
+[tools.logging](https://github.com/clojure/tools.logging) can use Timbre as its logging implementation (backend). This'll let tools.logging calls trigger Timbre logging calls.
+
+To do this:
+
+1. Ensure that you have the tools.logging [dependency](https://mvnrepository.com/artifact/org.clojure/tools.logging), and
+2. Require the `taoensso.timbre.tools.logging` namespace
+3. Call [`taoensso.timbre.tools.logging/use-timbre`](https://taoensso.github.io/timbre/taoensso.timbre.tools.logging.html#var-use-timbre)
+
+# Java logging
+
+[SLF4Jv2](https://www.slf4j.org/) can use Timbre as its logging backend. This'll let SLF4J logging calls trigger Timbre logging calls.
+
+To do this:
+
+1. Ensure that you have the SLF4J [dependency](https://mvnrepository.com/artifact/org.slf4j/slf4j-api) ( v2+ **only**), and
+2. Ensure that you have the Timbre SLF4J backend [dependency](https://clojars.org/com.taoensso/timbre-slf4j)
+
+When `com.taoensso/timbre-slf4j` (2) is on your classpath AND no other SLF4J backends are, SLF4J will automatically direct all its logging calls to Timbre.
+
+> Timbre needs SLF4J API **version 2 or newer**. If you're seeing `Failed to load class "org.slf4j.impl.StaticLoggerBinder"` it could be that your project is importing the older v1 API, check with `lein deps :tree` or equivalent.
+
+For other (non-SLF4J) logging like [Log4j](https://logging.apache.org/log4j/2.x/), [java.util.logging](https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html) (JUL), and [Apache Commons Logging](https://commons.apache.org/proper/commons-logging/) (JCL), use an appropriate [SLF4J bridge](https://www.slf4j.org/legacy.html) and the normal SLF4J config as above.
+
+In this case logging will be forwarded:
+
+1. From Log4j/JUL/JCL/etc. to SLF4J, and
+2. From SLF4J to Timbre