[doc] Doc and example improvements

README.md

@@ -5,7 +5,7 @@
 
 ### Structured telemetry library for Clojure/Script
 
-**Telemere** is a next-generation replacement for [Timbre](https://www.taoensso.com/timbre). It handles **structured and traditional logging**, **tracing**, and **basic performance monitoring** with a simple unified API.
+**Telemere** is a next-generation replacement for [Timbre](https://www.taoensso.com/timbre) that offers a simple **unified API** for **structured and traditional logging**, **tracing**, and **basic performance monitoring**.
 
 It helps enable Clojure/Script systems that are **observable**, **robust**, and **debuggable** - and it represents the refinement and culmination of ideas brewing over 12+ years in [Timbre](https://www.taoensso.com/timbre), [Tufte](https://www.taoensso.com/tufte), [Truss](https://www.taoensso.com/truss), etc.
 
@@ -48,7 +48,10 @@ See [here][GitHub releases] for earlier releases.
 - Fully [configurable](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options) **a/sync dispatch support**: blocking, dropping, sliding, etc.
 - Turn-key **sampling**, **rate-limiting**, and **back-pressure monitoring** with sensible defaults.
 
-> A comparison to the excellent [Mulog](https://github.com/BrunoBonacci/mulog) micro-logging library is provided [here](../../wiki/6-FAQ#how-does-telemere-compare-to-mulog).
+#### Comparisons
+
+- Telemere [compared](../../wiki/5-Migrating#from-timbre) to [Timbre](https://www.taoensso.com/timbre)
+- Telemere [compared](../../wiki/6-FAQ#how-does-telemere-compare-to-mulog) to [Mulog](https://github.com/BrunoBonacci/mulog)
 
 ## Video demo
 
@@ -193,8 +196,9 @@ See [here](../../wiki/4-Handlers) for more/upcoming handlers, community handlers
 ## Documentation
 
 - [Wiki][GitHub wiki] (getting started, usage, etc.)
-- API reference: [cljdoc][cljdoc docs] or [Codox][Codox docs]
+- API reference via [cljdoc][cljdoc docs] or [Codox][Codox docs]
-- Support: [Slack channel][] or [GitHub issues][]
+- Extensive [internal help](#internal-help) (no need to leave your IDE)
+- Support via [Slack channel][] or [GitHub issues][]
 - [General observability tips](../../wiki/7-Tips) (advice on building and maintaining observable Clojure/Script systems, and getting the most out of Telemere)
 
 ## Benchmarks

examples.cljc

@@ -147,8 +147,8 @@
 (t/with-min-level :trace ; Override global minimum level
   (t/with-signal (t/event! ::my-id1 :debug))) ; => {:keys [inst id ...]}
 
-;; Deny all signals in matching namespaces
+;; Disallow all signals in matching namespaces
-(t/set-ns-filter! {:deny "some.nosy.namespace.*"})
+(t/set-ns-filter! {:disallow "some.nosy.namespace.*"})
 
 ;;; Configuring handlers
 

wiki/5-Migrating.md

@@ -4,13 +4,13 @@ While [Timbre](https://taoensso.com/timbre) will **continue to be maintained and
 
 Telemere's functionality is a **superset of Timbre**, and offers *many* improvements including:
 
-- Improved performance
+- Better support for [structured logging](./1-Getting-started#data-types-and-structures)
-- Better support for structured logging
+- Better [performance](https://github.com/taoensso/telemere#benchmarks)
-- A cleaner and more flexible API
+- Better [documentation](https://github.com/taoensso/telemere#documentation)
-- Much better documentation
+- Better [included handlers](./4-Handlers##included-handlers)
-- Better built-in handlers
+- A more flexible [API](./1-Getting-started#usage) that unifies all telemetry and logging needs
-- Easier configuration in many cases
+- A more robust [architecture](./2-Architecture), free from all historical constraints
-- A more robust architecture, free from all historical constraints
+- Easier [configuration](./3-Config)
 
 Migrating from Timbre to Telemere should be straightforward **unless you depend on specific/custom appenders** that might not be available for Telemere (yet).
 

wiki/6-FAQ.md

@@ -134,9 +134,9 @@ Some particular **strengths of Telemere**:
 - Rich **dispatch control** (see [`help:handler-dispatch-options`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options))
 - Rich **environmental config** (see [`help:environmental-config`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:environmental-config)) for all platforms
 - Detailed **handler stats** (see [`get-handlers-stats`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#get-handlers-stats))
-- Extensive [in-IDE documentation](./1-Getting-started#internal-help)
 - Single **unified API** for all telemetry and traditional logging needs (see [`help:signal-creators`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-creators))
 - Lazy `:let`, `:data`, `:msg`, `:do` - evaluated only **after filtering**
+- Extensive [in-IDE documentation](./1-Getting-started#internal-help)
 
 Some particular **strengths of Mulog** that I'm aware of:
 
@@ -157,7 +157,7 @@ Ultimately I wrote Telemere because:
 1. I have some particular needs, including very complex and large-scale applications that benefit from the kind of flexibility that Telemere offers re: filtering, dispatch, environmental config, lazy (post-filter) evaluation, etc.
 2. I have some particular tastes re: my ideal API.
 3. I wanted something that integrated particularly well with [Tufte](https://taoensso.com/tufte) and could share an identical API for filtering, handlers, etc.
-4. I wanted a modern replacement for [Timbre](https://www.taoensso.com/timbre) users that offered a superset of its functionality and easy migration path.
+4. I wanted a modern replacement for [Timbre](https://www.taoensso.com/timbre) users that offered a superset of its functionality and an [easy migration path](./5-Migrating#from-timbre).
 
 # Other questions?