Insufficient links between guide and reference level docs makes splitting challenging

[lf-]

Observations

Currently there are efforts to split docs into guide vs reference level materials and this is likely great but the reference level docs no longer are next to the relevant guides. We need more deep links between nixpkgs and nix docs and nix.dev guide level materials.

related discussion https://logs.nixos.dev/room/!avYyleMexqjFHoqrME:nixos.org/?anchor=$1a-p0jIFGfppHqFadSnQIpoX40mUALH9qt7griX9qWk&offset=-10

Problem

Hard to get between high level overview (do we even have these materials? like a map between Nix concepts and how they're used in nixpkgs if at all), reference, and guides, especially starting at reference. It's true that Nix shouldn't assume nixpkgs (bull is out of the pen on that one in many cases code wise) but we should link to how nixpkgs uses each high level concept.

Approaches

Add more links and maybe write in the style guide where links are appropriate and how to integrate them.

Willing to help?

yeah

Priorities

Add 👍 to issues you find important.

[fricklerhandwerk]

we should link to how nixpkgs uses each high level concept

The Nixpkgs manual is probably the place to write that down. Similarly for NixOS I suppose.