4 files changed, 30 insertions, 8 deletions
diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md
index ab6f452..c4f18c7 100644
--- a/book/en/src/by-example/app.md
+++ b/book/en/src/by-example/app.md
@@ -7,11 +7,14 @@ This is the smallest possible RTIC application:
 ```
 
 All RTIC applications use the [`app`] attribute (`#[app(..)]`). This attribute
-must be applied to a `mod`-item. The `app` attribute has
-a mandatory `device` argument that takes a *path* as a value. This path must
-point to a *peripheral access crate* (PAC) generated using [`svd2rust`]
-**v0.14.x** or newer. The `app` attribute will expand into a suitable entry
-point so it's not required to use the [`cortex_m_rt::entry`] attribute.
+must be applied to a `mod`-item. The `app` attribute has a mandatory `device`
+argument that takes a *path* as a value. This must be a full path pointing to a
+*peripheral access crate* (PAC) generated using [`svd2rust`] **v0.14.x** or
+newer. More details can be found in the [Starting a new project](./new.md)
+section.
+
+The `app` attribute will expand into a suitable entry point so it's not required
+to use the [`cortex_m_rt::entry`] attribute.
 
 [`app`]: ../../../api/cortex_m_rtic_macros/attr.app.html
 [`svd2rust`]: https://crates.io/crates/svd2rust
diff --git a/book/en/src/by-example/new.md b/book/en/src/by-example/new.md
index 866a9fa..82681bf 100644
--- a/book/en/src/by-example/new.md
+++ b/book/en/src/by-example/new.md
@@ -52,7 +52,23 @@ $ curl \
     > src/main.rs
 ```
 
-That example depends on the `panic-semihosting` crate:
+The `init` example uses the `lm3s6965` device. Remember to adjust the `device`
+argument in the app macro attribute to match the path of your PAC crate, if
+different, and add peripherals or other arguments if needed. Although aliases
+can be used, this needs to be a full path (from the crate root). For many
+devices, it is common for the HAL implementation crate (aliased as `hal`) or
+Board Support crate to re-export the PAC as `pac`, leading to a pattern similar
+to the below:
+
+```rust
+use abcd123_hal as hal;
+//...
+
+#[rtic::app(device = crate::hal::pac, peripherals = true, monotonic = rtic::cyccnt::CYCCNT)]
+mod app { /*...*/ }
+```
+
+The `init` example also depends on the `panic-semihosting` crate:
 
 ``` console
 $ cargo add panic-semihosting
diff --git a/book/en/src/by-example/resources.md b/book/en/src/by-example/resources.md
index d082dfc..9d90fbe 100644
--- a/book/en/src/by-example/resources.md
+++ b/book/en/src/by-example/resources.md
@@ -1,4 +1,4 @@
-## Resources
+# Resources
 
 The framework provides an abstraction to share data between any of the contexts
 we saw in the previous section (task handlers, `init` and `idle`): resources.
@@ -116,7 +116,9 @@ are required to access the resource even if the resource is contended by several
 tasks running at different priorities. The downside is that the task only gets a
 shared reference (`&-`) to the resource, limiting the operations it can perform
 on it, but where a shared reference is enough this approach reduces the number
-of required locks.
+of required locks. In addition to simple immutable data, this shared access can
+be useful where the resource type safely implements interior mutability, with
+appropriate locking or atomic operations of its own.
 
 Note that in this release of RTIC it is not possible to request both exclusive
 access (`&mut-`) and shared access (`&-`) to the *same* resource from different
diff --git a/book/en/src/by-example/tips.md b/book/en/src/by-example/tips.md
index d8264c9..090b30a 100644
--- a/book/en/src/by-example/tips.md
+++ b/book/en/src/by-example/tips.md
@@ -116,6 +116,7 @@ Here's an example where `heapless::Pool` is used to "box" buffers of 128 bytes.
 ``` rust
 {{#include ../../../../examples/pool.rs}}
 ```
+
 ``` console
 $ cargo run --example pool
 {{#include ../../../../ci/expected/pool.run}}