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.
At the moment I’m trying to figure out 2 packages, for which I am very thankful I did not have:
zerotierone and shadowsocks.
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.
I think currently this is best dealt in a per-package basis. Some things are described in nixpkgs manual, BTW (and people often don’t discover that one).
For general approach… for packages we might standardize a
meta.foo attribute, as that’s relatively easy to use:
$ nix eval nixpkgs.bash.meta.description
"GNU Bourne-Again Shell, the de facto standard shell on Linux"
and e.g. the
nix-env or other UI might later get extended to help using that.
+1 on standardizing on some format, not necessarily README.md files scattered in directories.
I’d suggest that whatever solution we come up with it should be possible to aggregate that into the nixpkgs manual. Perhaps the
meta.description field as @vcunat suggests or another field next to that.
I’m not sure what is so wrong with a README file. Every repo in GH has one. It’s searchable (in page and search engine), supports versioning, it has nice formatting and it can be collocated to the actual package, and: it’s free and immediately available since there is no extra coding to make it work in search result (unlike meta.foo).
The only downside I see is for devs cloning and updating the repo will have extra data to download and store.
From what I can tell, the only 2 official ways to search Nixpkgs are the cli and NixOS Search - Loading.... If we can modify the web client, then sure, adding a
meta.configuration might be useful.
Having said that, I don’t think it will improve the UX when you search, since it’s going to add extra data to the response, which btw is already somewhat slow (no caching?).
Better to offload the storage and availabilty to GH, don’t you think?
You think search engines and GH won’t index the contents of
meta.foo? BTW, you can have both…
meta.foo = builtins.readFile ./README.md;
Here is a great example of what I think should/could be the standard: NixOS/nixpkgs/blob/master/doc/languages-frameworks/node.section.md in github (discourse won’t let me add the link).
Without those instructions a js/node dev as myself would be fumbling around for hours just trying to install some npm packages.