diff --git a/clap_generate/README.md b/clap_generate/README.md
index 17ce782f8b3..adf8b47b7b8 100644
--- a/clap_generate/README.md
+++ b/clap_generate/README.md
@@ -1 +1,14 @@
 # clap_generate
+
+[![Crates.io](https://img.shields.io/crates/v/clap_generate?style=flat-square)](https://crates.io/crates/clap_generate)
+[![Crates.io](https://img.shields.io/crates/d/clap_generate?style=flat-square)](https://crates.io/crates/clap_generate)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/master/LICENSE-APACHE)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/master/LICENSE-MIT)
+
+Generates completions (and other things) for [`clap`](https://github.com/clap-rs/clap) based CLIs
+
+* [Documentation][docs]
+* [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
+* [Website](https://clap.rs/)
+
+[docs]: https://docs.rs/clap_generate
diff --git a/clap_generate/src/lib.rs b/clap_generate/src/lib.rs
index f29672b923a..83f2c94e52a 100644
--- a/clap_generate/src/lib.rs
+++ b/clap_generate/src/lib.rs
@@ -5,7 +5,10 @@
 // See the [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) files in this repository
 // for more information.
 
-//! Generates stuff for [`clap`](https://github.com/clap-rs/clap) based CLIs
+//! Generates completions (and other things) for [`clap`](https://github.com/clap-rs/clap) based CLIs
+//!
+//! - For generating at compile-time, see [`generate_to`]
+//! - For generating at runtime, see [`generate`]
 
 #![doc(html_logo_url = "https://clap.rs/images/media/clap.png")]
 #![doc(html_root_url = "https://docs.rs/clap_generate/3.0.0-beta.4")]
@@ -36,9 +39,10 @@ pub use generators::Generator;
 #[doc(inline)]
 pub use shell::Shell;
 
-/// Generate a file for a specified generator at compile time.
+/// Generate a completions file for a specified shell at compile-time.
 ///
-/// **NOTE:** to generate the file at compile time you must use a `build.rs` "Build Script"
+/// **NOTE:** to generate the file at compile time you must use a `build.rs` "Build Script" or a
+/// [`cargo-xtask`]](https://github.com/matklad/cargo-xtask)
 ///
 /// # Examples
 ///