diff --git a/doc/languages-frameworks/beam.section.md b/doc/languages-frameworks/beam.section.md
index 5e85723085c1..2cb4863fc53b 100644
--- a/doc/languages-frameworks/beam.section.md
+++ b/doc/languages-frameworks/beam.section.md
@@ -44,11 +44,29 @@ There is also a `buildMix` helper, whose behavior is closer to that of `buildErl
 
 ## How to Install BEAM Packages {#how-to-install-beam-packages}
 
-BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. To install any of those builders into your profile, refer to them by their attribute path `beamPackages.rebar3`:
+BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users.
+To use any of those builders into your environment, refer to them by their attribute path under `beamPackages`, e.g. `beamPackages.rebar3`:
+
+::: {.example #ex-beam-ephemeral-shell}
+# Ephemeral shell
 
 ```ShellSession
-$ nix-env -f "<nixpkgs>" -iA beamPackages.rebar3
+$ nix-shell -p beamPackages.rebar3
 ```
+:::
+
+::: {.example #ex-beam-declarative-shell}
+# Declarative shell
+
+```nix
+let
+  pkgs = import <nixpkgs> { config = {}; overlays = []; };
+in
+pkgs.mkShell {
+  packages = [ pkgs.beamPackages.rebar3 ];
+}
+```
+:::
 
 ## Packaging BEAM Applications {#packaging-beam-applications}