4 ms·

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

> you'd have to read the nixpkgs source. https://nixos.org/manual/nixpkgs/stable/#trivial-builder-wri 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-support/trivial-builders.nix#L187-L199 https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-supp...

HotHotLava 5y ago
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.
- ghostwriter 5y ago
  `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.
rgoulter 5y ago
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.
dmitriid 5y ago
> 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
darkarmani 5y ago
> 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.
- ghostwriter 5y ago
  NixOS is production ready, productive teams that care about reproducibility use it in a variety of production environments already.

HotHotLava 5y ago

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.

ghostwriter 5y ago
`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.

rgoulter 5y ago

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.

dmitriid 5y ago

> 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

darkarmani 5y ago

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

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