I’m a nixos noob with a small suggestion for the documentation (not sure what category fits).
The Scenario: If I need to add piece of functionality to my nixos, I need to add one of the following to my configuration.nix: a service, a program, or a package. These three categories correspond roughly to large, medium, or small pieces of functionality.
The issue here is that the user needs to know IN ADVANCE whether a piece of functionality is large, medium or small because each is documented in a different location.
For example, I’m running the KDE desktop (a sub-feature of the xserver service) and want GTK apps to look good. According to the wiki, I need to install the dconf program. The issue is that there’s also a dconf package which you really should not use.
My Suggestion: the packages documentation should be enhanced to nudge users to a corresponding program or service if there is one. For example, “How to install dconf?” should say “programs.dconf.enable=true;” not “environment.systemPackages=[pkgs.dconf];”
Rather than manually modifying every relevant package doc, what if someone added an automation to the wiki itself that adds an extra comment if there’s an option named “programs.package-name”. (Or services.package-name Or virtualization.package-name…)
More or less because of that. There are far too many exceptions and edge cases for pure automation to be productive here. It’s why the current situation is so bad - automatically assigning installation instructions for all packages is simply inadequate.
Just as an example of how contrived these things can be, how do you automatically infer that linuxKernel.packages.linux_zen.nvidia_x11_production_open should not be used at all, but instead you should set hardware.nvidia.package to boot.kernelPackages.linux_zen.nvidia_x11_production (note the lack of open) and then enable hardware.nvidia.open?
Finding all the edge cases and automating everything else is likely going to be about as much effort as just dealing with the caveats while writing module documentation, and then having a meta link from packages to related modules, as @atemu suggests. Then you delete the generic copy-paste stuff that’s there currently and replace it with a generic “howto” link, also as @atemu suggests.
That would then overall result in a higher quality documentation story, because hand-written always beats automatically generated for this kind of thing (I assert with nothing but anecdotal evidence, but IME completely automated docs lack so much context that they’re effectively useless - case in point, current nixpkgs search - and while I have not seen it yet I imagine generating reference documentation with an LLM would be a fantastically bad idea).
Did I mention I like @atemu 's suggestion? Is there an RFC for it yet? Is one even needed?
I don’t think so. Unless there’s significant opposition to the idea requiring a sort of community consensus, I think an RFC would be overkill for a moderate UX improvement of the NixOS search page.
Some parts of the suggestion such as @roberth’s idea of creating links between packages and modules are just obviously good and should require no broad community involvement in the decision to do it, just a PR.
Other parts might require a decision on the “philosophy” of how we document Nix but I think that’d better be left to the Nix documentation team. Anyone who cares strongly about our documentation should be part of that team anyways.
Instead of replacing the existing manually-crafted documentation, just append or prepend the auto-created link and text.
@tlater mentioned complicated edge cases. I’m a great believer in the 80/20 rule as it applies to work - 80% of the effort in a project goes into implementing 20% of the functionality. So I’d hit the simple cases and ignore (for now) the complicated edge cases.