diff --git a/docs/manual/src/Motivation.md b/docs/manual/src/Motivation.md
index 1cea93d61c..d10edb0a49 100644
--- a/docs/manual/src/Motivation.md
+++ b/docs/manual/src/Motivation.md
@@ -28,11 +28,11 @@ continues to evolve.
 Using UniFFI, you can:
 
 * Implement your software component as a `cdylib` crate in Rust; let's say the code is in `./src/lib.rs`.
-* Specify the desired component API using an *Interface Definition Language* (specifically, a variant of WebIDL) in a separate file like `./src/lib.udl`.
-* Run `uniffi-bindgen scaffolding ./src/lib.udl` to generate a bunch of boilerplate rust code that exposes this API as a C-compatible FFI layer,
-  and include it as part of your crate.
+* Optionally, describe parts of your component API using proc-macros directly in `lib.rs`.
+* Optionally, describe parts of your component API using an *Interface Definition Language* in a separate file like `./src/lib.udl`. UniFFI will generate a bunch of boilerplate Rust code that exposes this API as a C-compatible FFI layer, and include it as part of your crate.
 * `cargo build` your crate as normal to produce a shared library.
-* Run `uniffi-bindgen generate ./src/lib.udl -l kotlin` to generate a Kotlin library that can load your shared library
+* Run `uniffi-bindgen generate ... -l kotlin` (see [the bindgen docs](./tutorial/foreign_language_bindings.md) for omitted arg details)
+  to generate a Kotlin library that can load your shared library
   and expose it to Kotlin code using your nice high-level component API!
   * Or `-l swift` or `-l python` to produce bindings for other languages.
 
diff --git a/docs/manual/src/index.md b/docs/manual/src/index.md
index e6cc886b5c..c0fa836645 100644
--- a/docs/manual/src/index.md
+++ b/docs/manual/src/index.md
@@ -3,12 +3,14 @@
 UniFFI is a tool that automatically generates foreign-language bindings targeting Rust libraries.
 The repository can be found on [github](https://github.com/mozilla/uniffi-rs/).
 It fits in the practice of consolidating business logic in a single Rust library while targeting multiple platforms, making it simpler to develop and maintain a cross-platform codebase.
-Note that this tool will not help you ship a Rust library to these platforms, but simply not have to write bindings code by hand. [Related](https://i.kym-cdn.com/photos/images/newsfeed/000/572/078/d6d.jpg).
+Note that this tool will not help you ship a Rust library to these platforms, but it will help you avoid writing bindings code by hand.
+[Related](https://i.kym-cdn.com/photos/images/newsfeed/000/572/078/d6d.jpg).
 
 ## Design
 
-UniFFI requires to write an Interface Definition Language (based on [WebIDL](https://heycam.github.io/webidl/)) file describing the methods and data structures available to the targeted languages.
-This .udl (UniFFI Definition Language) file, whose definitions must match with the exposed Rust code, is then used to generate Rust *scaffolding* code and foreign-languages *bindings*. This process can take place either during the build process or be manually initiated by the developer.
+UniFFI requires you to describe your interface via either proc-macros or in an Interface Definition Language (based on [WebIDL](https://webidl.spec.whatwg.org/)) file.
+These definitions describe the methods and data structures available to the targeted languages, and are used to generate Rust *scaffolding* code and foreign-language *bindings*.
+This process can take place either during the build process or be manually initiated by the developer.
 
 ![uniffi diagram](./uniffi_diagram.png)
 
diff --git a/fixtures/ext-types/README.md b/fixtures/ext-types/README.md
index 91f9ba421a..cb11c8ab61 100644
--- a/fixtures/ext-types/README.md
+++ b/fixtures/ext-types/README.md
@@ -1,6 +1,13 @@
-This directory contains the tests for external types -- types defined in one crate and used in a
-different one.
+This directory contains the tests for external types - cross-crate depedencies and libraries
+to tie them together.
 
-- `guid` and `uniffi-one` are dependent crates that define types exported by UniFFI
-- `lib` is a library crate that depends on `guid` and `uniffi-one`
-- `proc-macro-lib` is another library crate, but this one uses proc-macros rather than UDL files
+- `lib` is a library crate that depends on various other crates.
+- `proc-macro-lib` is another library crate, but this one uses proc-macros rather than UDL files.
+
+The various other crates all inter-relate and are ultimately consumed by the above libs:
+- `custom-types` is all about wrapping types (eg, Guid, Handle) in a native type (eg, String, u64)
+- `uniffi-one` is just a normal other crate also using uniffi.
+- `sub-lib` itself consumes and exposes the other types.
+- `external-crate` doesn't depend on uniffi but has types we expose.
+
+etc.
diff --git a/fixtures/ext-types/sub-lib/README.md b/fixtures/ext-types/sub-lib/README.md
index 41c153fde4..48fd1db921 100644
--- a/fixtures/ext-types/sub-lib/README.md
+++ b/fixtures/ext-types/sub-lib/README.md
@@ -1,3 +1,3 @@
-This is a "sub library" - it is itself a "library" which consumes types from
+This is a "sub library" - ie, a crate which consumes types from
 other external crates and *also* exports its own composite types and trait
 implementations to be consumed by the "main" library.