Hacker News Reader

Comment by rgoulter | Hacker News Reader

Nix is wonderful, but absolutely is under-documented. (In part due to a small community, etc.).

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...

View on HN

> you'd have to read the nixpkgs source. https://nixos.org/manual/nixpkgs/stable/#trivial-builder-wri...

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...

It's one thing to look at the source, it's another thing to know that you have to look inside `pkgs/build-support/trivial-builders.nix` to find the documentation. One of the main advantages of reference documentation is a central place to look up what things do.

`writeScriptBin` is the second topmost link on Google search that leads directly to that file in a central repository of nixpkgs. Unique function names have the advantage of being transparent references that you can find either via google, or github search, or grep on your local checkout of nixpkgs.

In 2022, I think it's a reasonable expectation that API documentation can be accessed as rendered HTML. -- e.g. Haskell's or Rust's documentation even links to the source for the packages.

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.

> Is it too much to ask from developers in 2022?

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

> Is it too much to ask from developers in 2022?

It's not too much to ask for non-production ready software. If nixos is supposed to be production ready, then yes.

NixOS is production ready, productive teams that care about reproducibility use it in a variety of production environments already.

Reply on news.ycombinator.com