Is it too much to ask from developers in 2022? At source, the function is well documented and is provided with an example [1]. The only missing part is a rendered HTML with the same information.
[1] https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-supp...
On the other hand, I think it's fair to say NixOS will sometimes require a high level of involvement from its users. When something goes wrong on another OS, it's easy to search for the answer. With NixOS, you have to understand both the Linux part, and the NixOS part.
In 2022 it's not too much to ask from the developers of the tools to provide:
- consistent and up-to-date documentation (that's built and updated together with the source code)
- consistent, readable and understandable error messages
It's not too much to ask for non-production ready software. If nixos is supposed to be production ready, then yes.
A couple of examples I've run into:
https://github.com/NixOS/nix/issues/2259 showed people trying to make use of the "hello world" package which was given in the NixPkgs manual, but couldn't quite figure out how to get it to build.
e.g. if you want a package that's a simple script, "writeScriptBin" seems like what you'd want. -- But it's really not clear how to use it from the manual; you'd have to read the nixpkgs source. https://nixos.org/manual/nixpkgs/stable/#trivial-builder-wri...