diff --git a/cranelift/docs/isle-integration.md b/cranelift/docs/isle-integration.md
index 040407b590..fde0e16436 100644
--- a/cranelift/docs/isle-integration.md
+++ b/cranelift/docs/isle-integration.md
@@ -16,29 +16,38 @@ Documentation on the ISLE language itself can be found
 
 The build integration is inside of `cranelift/codegen/build.rs`.
 
-For regular builds, we check a manifest that records the file hashes of the ISLE
-source files that went into building a given ISLE-generated Rust file. If the
-hashes of these files on disk don't match the hashes in the manifest, then the
-ISLE-generated Rust file is stale and needs to be rebuilt. In this case, the
-`build.rs` will report a build error. This way, downstream crates that use
-Cranelift don't need to build ISLE, and get fewer transitive dependencies and
-faster build times.
+The ISLE compiler is built as a build-dependency, and the build script then
+uses it to compile ISLE source to generated Rust code. In other words, the ISLE
+compiler behaves as an additional compile step, and ISLE source is rebuilt just
+like any Rust source would be. Nothing special needs to be done when editing
+ISLE.
 
-To intentionally rebuild ISLE-generated Rust files, use the `rebuild-isle` Cargo
-feature with `cranelift-codegen`:
+Sometimes, it's desirable to see what code is actually generated. By default,
+the generated code is placed in a Cargo-managed path in `target/`. If you want
+to see the source instead, invoke Cargo with the optional feature
+`isle-in-source-tree` as follows:
 
 ```shell
-$ cargo check -p cranelift-codegen --features rebuild-isle
+$ cargo check -p cranelift-codegen --features isle-in-source-tree
 ```
 
-When this feature is active, we rerun the ISLE compiler on the ISLE sources to
-create the new versions of the ISLE-generated Rust files and update the manifest
-files.
+This will place the ISLE source in `cranelift/codegen/isle_generated_code/`,
+where you can inspect it, debug by setting breakpoints in it, etc. Note that if
+you later build without this feature, the build system will require you to
+delete the directory. This is to ensure that no out-of-date copies exist, which
+could cause significant confusion.
+
+If there are any errors during ISLE compilation (e.g., a type mismatch), you
+will see a basic error message with a file, line number, and one-line error. To
+see a more detailed output with context, `--features isle-errors` can be used.
+This will leverage the `miette` error-reporting library to give pretty-printed
+errors with source context.
 
 Additionally, the `cranelift-codegen-meta` crate will automatically generate
 ISLE `extern` declarations and helpers for working with CLIF. The code that does
 this is defined inside `cranelift/codegen/meta/src/gen_inst.rs` and it creates
-the `cranelift/codegen/src/clif.isle` file.
+the `clif.isle` file in the `target/` output directory, which is subsequently
+read by the ISLE compiler as part of its prologue.
 
 ## Where are the relevant files?
 
@@ -47,10 +56,9 @@ the `cranelift/codegen/src/clif.isle` file.
 * `cranelift/codegen/src/prelude.isle`: Common definitions and declarations for
   ISLE. This gets included in every ISLE compilation.
 
-* `cranelift/codegen/src/clif.isle`: Auto-generated declarations and helpers for
-  working with CLIF inside ISLE. Generated by `cranelift/codegen/build.rs` when
-  the `rebuild-isle` feature is enabled. This gets included in every ISLE
-  compilation.
+* `target/.../out/clif.isle`: Auto-generated declarations and helpers for
+  working with CLIF inside ISLE. Generated by `cranelift/codegen/build.rs`.
+  This gets included in every ISLE compilation.
 
 * `cranelift/codegen/src/machinst/isle.rs`: Common Rust code for gluing
   ISLE-generated code into a target architecture's backend. Contains
@@ -70,10 +78,6 @@ the `cranelift/codegen/src/clif.isle` file.
   for this ISA. Contains implementations of ISA-specific `extern` helpers
   declared in ISLE.
 
-* `cranelift/codegen/src/isa/<arch>/lower/isle/generated_code.rs`: The
-  ISLE-generated Rust code to perform instruction and CLIF-to-`MachInst`
-  lowering for each target architecture.
-
 ## Gluing ISLE's generated code into Cranelift
 
 Each ISA-specific, ISLE-generated file is generic over a `Context` trait that