This pull request has been mentioned on Nix community. There might be relevant details there:

https://discourse.nixos.org/t/documentation-for-configuring-nixpkgs/2268/1

👎 on adding undiscoverable READMEs. Using Nixpkgs should not require browsing the Nixpkgs source tree.

-1 on adding undiscoverable READMEs. Using Nixpkgs should not require browsing the Nixpkgs source tree.

this reminded me that while looking in/at the "source tree"
eg directory hierarchy

it seams a shame the effort is made to organize packages ect into this tree
and as you say

Using Nixpkgs should not require browsing the Nixpkgs source tree.

but!! it would be nice (IMHO) for users to be able to discover packages ( or even as this issue suggests documentation ) by navigating a tree
eg to look for games in dir tree @ NixOS/nixpkgs/../pkgs/games

while it makes sense not browsing -THE- source tree , it could be possible to allow browsing -a tree- of package's and or documentation that mirrors the nice directory hierarchy of the Nixpkgs source tree!

at least that is from my point of view !!

@edolstra

-1 on adding undiscoverable READMEs

How is a Github README undiscoverable when it is indexed by [insert your favorite search engine name here]? In my short life (3 weeks) using Nix, I have found 75% of the packages I search/need in Google, linking directly into this Github repo, since the cli (nix-env -qa) does not return (fuzzy) results unless I know the "correct" name of the package. Try searching nix-env -qaP shadowsocks, there is 2 packages but neither one is returned by the cli (nor GH general search unless you "Search this repository"). Google finds them no problem. Maybe there's a way to search meta data (description) through the cli I don't know about?
That's still not address the lack of configuration documentation.

Using Nixpkgs should not require browsing the Nixpkgs source tree.

Indeed, so what is your solution?
I am suggesting one which I am pretty sure is not the canonical/correct one, but it fixes the issue I am addressing, which I strongly believe should be addressed.

What about some meta.foo attribute? I'm not sure whether to discuss that here or on discourse where I've put more details.

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 https://nixos.org/nixos/packages.html. 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?

Here is a great example of what I think should/could be the standard: https://github.com/NixOS/nixpkgs/blob/master/doc/languages-frameworks/node.section.md
Without those instructions a js/node dev as myself would be fumbling around for hours just trying to install some npm packages.

@acyuta108 if you still think this kind of change is needed. File an RFC at https://github.com/NixOS/rfcs . I'm closing as too much time has passed for this PR too ancient.