Put "Best practices" parts where they belong

[9999years]

Observations

diataxis.fr describes how-to guides as:

• Practical steps
• That serve our work in Nix (rather than our study of Nix)
• That are task-oriented

The "Best practices" section on nix.dev does not contain guides. They are neither a series of steps nor task-oriented.

Approaches

The best practices section should probably be included with the reference material, possibly merged into the relevant descriptions of the language features in the Nix manual (for URL syntax, rec {}, with, <lookup paths>, the // merge operator, and reproducible paths) or the Nixpkgs manual (for "Reproducible Nixpkgs configuration").

Willing to help?

Sure, as long as I can just move the documentation around. I don't want to submit a PR and then get told to rewrite the docs to make them better.

Priorities

Add 👍 to issues you find important.

[fricklerhandwerk]

I'd very much support that. That's the sort of clean-up I always had in mind. Unfortunately I don't see "just move" happening because there are so many moving parts. There's barely a chance to not do rewriting simply to be able to fit things in.

The Technically Correct but very expensive way to do it would be this (ordered roughly from most to least involved):

• Move the reproducible Nixpkgs configuration tip to the configuration section of the Nixpkgs manual (which is a mess and needs a complete rewrite to even find a good place for this)
• Merge pinning Nixpkgs and the other pinning Nixpkgs (I have a very messy WIP branch that got confused on the path down a rabbit hole) and add it to the Nix manual
• Rewrite the the lookup paths tip and wire it up so there is no duplication with e.g. nix-channel documentation
• Add nested attribute set update tip to the troubleshooting section, move the examples to the Nix manual operators page, and extend the lib.recursiveUpdate piece with the problem statement and link to that Nix manual page.
• Rewrite the reproducible source paths example to use builtins.derivation
• Find places in the language section for the other tips. (Technically there is also a licensing issue, because nix.dev is CC-BY-SA and Nix is LGPL. sigh)

And on the way keep all URLs working by adding redirects appropriately, synchronising PRs across repos once the information has a new place.

But maybe we can get this done piecemeal.

[9999years]

Unfortunately I don't see "just move" happening because there are so many moving parts. There's barely a chance to not do rewriting simply to be able to fit things in.

We don't need to make a monolithic ticket for this. It's OK to move it and then create follow-up tickets for rewriting the relevant material. Small incremental improvements are easier to work with.