BEAM docs: recommend `nix-shell -p` and `shell.nix` instead of `nix-env` (#255131)

* BEAM docs: recommend `nix-shell -p` and `shell.nix` instead of `nix-env`

Co-authored-by: asymmetric <lorenzo@mailbox.org>

1 files changed, 20 insertions, 2 deletions

diff --git a/doc/languages-frameworks/beam.section.md b/doc/languages-frameworks/beam.section.md
index 5e85723085c12..2cb4863fc53be 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}