diff --git a/README.md b/README.md
index 505fcc0..74335f2 100644
--- a/README.md
+++ b/README.md
@@ -14,17 +14,14 @@ pip install nh3
 
 ## Usage
 
-```python
-import nh3
-
-print(nh3.clean("<b><img src=\"\">I'm not trying to XSS you</b>"))
-```
+See [the documentation](https://nh3.readthedocs.io/en/latest/).
 
 ## Performance
 
-Running on MacBook Air (M2, 2022)
+A quick benchmark showing that nh3 is about 20 times faster than the deprecated [bleach](https://pypi.org/project/bleach/) package.
+Measured on a MacBook Air (M2, 2022).
 
-```python
+```ipython
 Python 3.11.0 (main, Oct 25 2022, 16:25:24) [Clang 14.0.0 (clang-1400.0.29.102)]
 Type 'copyright', 'credits' or 'license' for more information
 IPython 8.9.0 -- An enhanced Interactive Python. Type '?' for help.
diff --git a/src/lib.rs b/src/lib.rs
index f3404f1..fdeed57 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -5,7 +5,7 @@ use pyo3::exceptions::PyTypeError;
 use pyo3::prelude::*;
 use pyo3::types::{PyString, PyTuple};
 
-/// Sanitizes an HTML fragment in a string according to the configured options.
+/// Sanitize an HTML fragment according to the given options.
 ///
 /// :param html: Input HTML fragment
 /// :type html: ``str``
@@ -172,7 +172,7 @@ fn clean(
     Ok(cleaned)
 }
 
-/// Turn an arbitrary string into unformatted HTML
+/// Turn an arbitrary string into unformatted HTML.
 ///
 /// This function is roughly equivalent to PHP’s htmlspecialchars and htmlentities.
 /// It is as strict as possible, encoding every character that has special meaning to the HTML parser.
@@ -186,11 +186,11 @@ fn clean_text(py: Python, html: &str) -> String {
     py.allow_threads(|| ammonia::clean_text(html))
 }
 
-/// Determine if a given string contains HTML
+/// Determine if a given string contains HTML.
 ///
-/// This function is parses the full string into HTML and checks if the input contained any HTML syntax.
+/// This function parses the full string and checks for any HTML syntax.
 ///
-/// Note: This function will return positively for strings that contain invalid HTML syntax
+/// Note: This function will return True for strings that contain invalid HTML syntax
 /// like ``<g>`` and even ``Vec::<u8>::new()``.
 ///
 /// :param html: Input string