nix-doc VS nix-book

I love nix, I've been using it for the last 2 years, I have a very stable setup from these 2 years of effort [0], and I just can't recommend Nix for Linux beginners, why?

It's not because of the nix language, It's not because of the CLI, it's because everything is scattered, you have to consult many places to find out how to do things with Nix, here is an example:

Usually, when I need a new complex program, like Steam, I first check the system-wide configuration [1], the wiki [2] and the package list [3], if I just want it on my user, I need to check if Home Manager has an option [4], if it doesn't, I can try using the "home.packages" option. Now, if I need to override something on the package, I need to remember how to do it with [5] [6] (while checking the source code for the package in parallel to find the options).

And then sometimes, on very rare occasions, I need to fine tune something with the nix language, so I need to check the builtins/lib docs [7], but some builtins are not there, so I need to either use nix-doc [8] or find the docs inside the code-bases [9] [10] (they are split between both repos)

For me, this is one of the main pain points of using Nix / NixOS that needs to be solved.

[0] - https://github.com/shiryel/nixos-dotfiles

[1] - https://search.nixos.org/options

[2] - https://nixos.wiki/wiki/Steam

[3] - https://search.nixos.org/packages

[4] - https://mipmip.github.io/home-manager-option-search/

[5] - https://nixos.org/manual/nixos/stable/#sec-customising-packa...

[6] - https://nixos.org/guides/nix-pills/nixpkgs-overriding-packag...

[7] - https://teu5us.github.io/nix-lib.html

[8] - https://github.com/lf-/nix-doc

[9] - https://github.com/NixOS/nix

[10] - https://github.com/NixOS/nixpkgs

This seems more approachable than NixOS/Guix, which I see as state or the art for declarative hosts.

https://discourse.nixos.org/t/documentation-team-flattening-... aims to flatten the learning curve for NixOS.

We're onto the pedagogy thing. Check out the Nix book efforts: https://discourse.nixos.org/t/documentation-team-flattening-....

Regarding the language and "configurations" specifically, you might like what we do with Nickel: https://github.com/tweag/nickel. Research project showing a potential future for Nix.

Wouldn't say there's a steep learning curve for the language itself, it's pretty easy to get a grasp around it imo. Here's a helpful page I used to quickly get familiar with the language: https://github.com/tazjin/nix-1p

What's rather messy about Nix is nixpkgs with its helper functions all over the place alongside pretty shallow / non-existent documentation (which is unrelated to the language). Thankfully they've started to work on that recently: https://discourse.nixos.org/t/documentation-team-flattening-...

yess https://github.com/NixOS/nix-book

there are efforts to better document the whole ecosystem (https://github.com/NixOS/nix-book)