I would like to encourage devs contributing to Nixpkgs repositories to add a README.md for any package that requires configuration. I learnt a great deal about Nix and NixOS in the past 2 weeks, since I dove head-first, thanks to the great design of the package manager and the OS, and the discussions and contributions, but in many cases it would be a better user experience, for noobs in Nix or linux, to have a proper documentation page appended to the nix package/derivation in Github.
This definitely applies to packages that require a config file or one that add a systemd service or udev rules.
Now, the nix derivations are not impossible to read, but for a non-Haskell or a new user, it’s a bit tough to figure out where (local .nixpkgs/config.nix or /etc/nixos/configuration.nix) and how to structure/setup the configuration. I have seen a few packages have some #configuration block at the bottom of the nix file but it wouldn’t take much effort to have a nicely formatted and simple documentation.
I also think this will greatly reduce the learning curve and teach new comers the proper and (hopefully) standardize way to install and setup packages in Nix or NixOS.
Don’t get me wrong I am very thankful for the ppl who wrote these great compliation/derivation, and I didn’t have to(!), but the extra documentation would make the Nix and NixOS experience.
I have created a pull request in GH for this proposal and will contact the creator(s) of the packages mentioned above to push the config documentaion as I have suggested.