Add more docs
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..2eb012a
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.0.0 :tada:
+
+* the carate is renmaed to `text-size` from `text_unit`
+
+Transition table:
+- `TextUnit::of_char(c)` ⟹ `TextSize::of(c)`
+- `TextUnit::of_str(s)` ⟹ `TextSize::of(s)`
+- `TextUnit::from_usize(size)` ⟹ `TextSize::try_from(size).unwrap_or_else(|| panic!(_))`
+- `unit.to_usize()` ⟹ `usize::from(size)`
+- `TextRange::from_to(from, to)` ⟹ `TextRange::new(from, to)`
+- `TextRange::offset_len(offset, size)` ⟹ `TextRange::from_len(offset, size)`
+- `range.start()` ⟹ `range.start()`
+- `range.end()` ⟹ `range.end()`
+- `range.len()` ⟹ `range.len()`
+- `range.is_empty()` ⟹ `range.is_empty()`
+- `a.is_subrange(b)` ⟹ `b.contains_range(a)`
+- `a.intersection(b)` ⟹ `a.intersect(b)`
+- `a.extend_to(b)` ⟹ `a.cover(b)`
+- `range.contains(offset)` ⟹ `range.contains(point)`
+- `range.contains_inclusive(offset)` ⟹ `range.contains_inclusive(point)`
diff --git a/src/lib.rs b/src/lib.rs
index b39cb18..07dc5e8 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,19 @@
//! Newtypes for working with text sizes/ranges in a more type-safe manner.
//!
+//! This library can help with two things:
+//! * Reducing storage requirenments for offsets and ranges, under the
+//! assumption that 32 bits is enough.
+//! * Providing standard vocabulary types for applications where text ranges
+//! are pervasive.
+//!
+//! However, you should not use this library simply because you work with
+//! strings. In the overhelming majority of cases, using `usize` and
+//! `std::ops::Range<usize>` is better. In particular, if you are publishing a
+//! library, using only std types in the interface would make it more
+//! interoperable. Similarly, if you are writing something like a lexer, which
+//! produces, but does not *store* text ranges, than sticking to `usize` would
+//! be better.
+//!
//! Minimal Supported Rust Version: latest stable.
#![forbid(unsafe_code)]
diff --git a/src/range.rs b/src/range.rs
index c80e535..50fcf82 100644
--- a/src/range.rs
+++ b/src/range.rs
@@ -9,20 +9,6 @@
/// A range in text, represented as a pair of [`TextSize`][struct@TextSize].
///
/// It is a logic error for `start` to be greater than `end`.
-///
-/// # Translation from `text_unit`
-///
-/// - `TextRange::from_to(from, to)` ⟹ `TextRange::new(from, to)`
-/// - `TextRange::offset_len(offset, size)` ⟹ `TextRange::from_len(offset, size)`
-/// - `range.start()` ⟹ `range.start()`
-/// - `range.end()` ⟹ `range.end()`
-/// - `range.len()` ⟹ `range.len()`
-/// - `range.is_empty()` ⟹ `range.is_empty()`
-/// - `a.is_subrange(b)` ⟹ `b.contains_range(a)`
-/// - `a.intersection(b)` ⟹ `a.intersect(b)`
-/// - `a.extend_to(b)` ⟹ `a.cover(b)`
-/// - `range.contains(offset)` ⟹ `range.contains(point)`
-/// - `range.contains_inclusive(offset)` ⟹ `range.contains_inclusive(point)`
#[derive(Default, Copy, Clone, Eq, PartialEq, Hash)]
pub struct TextRange {
// Invariant: start <= end
diff --git a/src/size.rs b/src/size.rs
index 3a2a281..3a0d34b 100644
--- a/src/size.rs
+++ b/src/size.rs
@@ -21,13 +21,6 @@
///
/// These escape hatches are primarily required for unit testing and when
/// converting from UTF-8 size to another coordinate space, such as UTF-16.
-///
-/// # Translation from `text_unit`
-///
-/// - `TextUnit::of_char(c)` ⟹ `TextSize::of(c)`
-/// - `TextUnit::of_str(s)` ⟹ `TextSize::of(s)`
-/// - `TextUnit::from_usize(size)` ⟹ `TextSize::try_from(size).unwrap_or_else(|| panic!(_))`
-/// - `unit.to_usize()` ⟹ `usize::from(size)`
#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct TextSize {
pub(crate) raw: u32,
