diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md
index 556af6625c0..7cbb9aefe5c 100644
--- a/src/doc/trpl/documentation.md
+++ b/src/doc/trpl/documentation.md
@@ -196,10 +196,10 @@ This will highlight according to whatever language you're showing off.
 If you're just showing plain text, choose `text`.
 
 It's important to choose the correct annotation here, because `rustdoc` uses it
-in an interesting way: It can be used to actually test your examples, so that
-they don't get out of date. If you have some C code but `rustdoc` thinks it's
-Rust because you left off the annotation, `rustdoc` will complain when trying to
-generate the documentation.
+in an interesting way: It can be used to actually test your examples in a
+library crate, so that they don't get out of date. If you have some C code but
+`rustdoc` thinks it's Rust because you left off the annotation, `rustdoc` will
+complain when trying to generate the documentation.
 
 ## Documentation as tests
 
@@ -377,8 +377,8 @@ $ rustdoc --test path/to/my/crate/root.rs
 $ cargo test
 ```
 
-That's right, `cargo test` tests embedded documentation too. However,
-`cargo test` will not test binary crates, only library ones. This is
+That's right, `cargo test` tests embedded documentation too. **However,
+`cargo test` will not test binary crates, only library ones.** This is
 due to the way `rustdoc` works: it links against the library to be tested,
 but with a binary, there’s nothing to link to.
 
diff --git a/src/doc/trpl/testing.md b/src/doc/trpl/testing.md
index a5a0127031a..cbf33febf87 100644
--- a/src/doc/trpl/testing.md
+++ b/src/doc/trpl/testing.md
@@ -355,8 +355,8 @@ Let's finally check out that third section: documentation tests.
 Nothing is better than documentation with examples. Nothing is worse than
 examples that don't actually work, because the code has changed since the
 documentation has been written. To this end, Rust supports automatically
-running examples in your documentation. Here's a fleshed-out `src/lib.rs`
-with examples:
+running examples in your documentation (**note:** this only works in library
+crates, not binary crates). Here's a fleshed-out `src/lib.rs` with examples:
 
 ```rust,ignore
 //! The `adder` crate provides functions that add numbers to other numbers.