This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/programs-foo-enable-true-vs-systempackages-foo-is-confusing/5534/8

Rendered:

Nice. I think it may be nice to have wording with nixos-option and a link to options.html. Where does ch-options link to? _{The docs system is a bit hard to navigate.}

#ch-options links to the Options appendix, which, on the web, is located at options.html.

IMHO, nixos-option is not very useful for discovery unless you already roughly know what option you want – not all packages are programs.

So #ch-options links to https://nixos.org/nixos/manual/options.html?

@jonringer's quote from the forums is good. Here's an updated version with more detail:

Generally it is recommended to use options instead of environment.systemPackages for configuring which packages are installed. Search available options at nixos.org/nixos/options.html. Options are smart about system effects needed for applications/services to run correctly.

For example,

• setting virtualization.docker.enable = true will create the necessary groups, install the docker-daemon, install the docker cli, and a few other things to enable normal docker usage.
• setting programs.zsh.enable = true will install zsh along with nix-zsh-completions and other features by default, whereas installing zsh by writing environment.systemPackages = [pkg.zsh] will install only zsh without nix-zsh-completions or other features.

Not all packages are available with a programs.<package-name>.enable (or similar) option, and in those cases installing them via environment.systemPackages is the only way.

@jtojnar I edited the above. Can you adapt that? I think it is better as not a "note" section.

Not really sure if this would not derail the section too much. Especially for something that is not relevant to the majority of packages.

I also think @trusktr's message is somewhat misleading - most of the time, just installing the package is just fine, sometimes it needs some custom dbus or udev magic, for which modules exist, but we don't have modules for all packages in nixpkgs.

I'd propose to merge @jtojnar 's version for now (as it already improves the situation quite a lot!), and if we come up with something better, do that in a follow-up PR.

Yay, thanks so much @jtojnar ❇️ . This is an extremely important part of documentation that was missing.

Correct me if I'm wrong, but this page as of now is still missing any mention that packages can (and when possible, should?) be installed as modules: https://nixos.org/manual/nixos/stable/index.html#sec-package-management

The note introduced in this PR did end up in the docs:

Do you have a proposal on how to better word this?

The way I read the current note is like this: "Some packages are hard to install and you will fail if you attempt to follow the guide above. So in order to install them, you'll need to play with their options by following this other guide".

The wording is very unclear that "options" actually refers to an altogether different way of installing software (via modules) and it does not mention that the same package can be often installed as a package or as a module (that does the same thing + configuration) and that in fact modules should be preferred (?) when possible.

I'm not knowledgeable enough about the system to suggest how it should be worded, so I'm only reporting from a user's point of view, but in my opinion the way it should be formatted is something like this:

In addition to installing packages by adding them to the list of system packages, some of them can be installed using a mechanism of options/modules:
programs.steam.enable=true;
This way should be preferred when available because in addition to installing packages it also configures the environment, here's how you search for packages that are available via modules and here's a link of where to read on more things that are available via options.

It's even more confusing that there's more ways to install software into the user's environment and it's very unclear for a new user which way is supposed to be used and why, it really needs examples with code and typical usecases as well as best practices in my opinon.

TL;DR: currently it's very unclear that "options" actually refers to an alternative (and actually preferred) way of installing software.

cc @roberth