this is a replacement for current search for packages and options
apart from being on par with current search functionality it also does a better job at finding more relevant results (Hint: try searching for “ghc” and compare the results)
this experiments are not limited only to nix cli, but can be about website, documentation, etc…
the experiment is going to be - for now - only announced here on discourse and we will be looking for ~5 participants. once we become more fluent with running this experiments we hope to invite more.
we still need to discuss: (1) what do we want to measure (2) how do we collect the results and present them at the end
This was a bit controversial topic but we found a compromise for the time being. I’m extremely proud that even when we disagree on certain things we know that putting a newcomers first is our top priority.
Your discussion on the last big bullet point Guides on nixos.org made me think a bit about the documentation and why I personally have a lot of struggles with it. I’m not sure if it’s just me, but I don’t have any concerns about the documentation tool @domenkozar used for https://nix.dev. The reason I think https://nix.dev won’t help making NixOS any more “mainstream” is that it’s pretty much just redundant information.
My experience with the probably best documented distribution (Archlinux) is that there is one wiki which will tell you all the things you need. While using Archlinux (and Manjaro) the archwiki was the only official documentation I ever needed. I want to install it? Arch wiki has one installer page. I want to create a new package? Arch wiki has one “how to add a package” page.
For NixOS, it seems to be the exact opposite. There is not just one page explaining how to do stuff, there are many.
Two very basic examples:
When I google “Install NixOS” I initially get the NixOS Manual (which I think is good). But then the third link in the installation guide links me to NixOS Installation Guide - NixOS Wiki “for a number of alternative methods” if I don’t want to use a USB. A second installation guide? Why is not just everything in one place?
When I google for “NixOS create package” the first 3 results are Nixpkgs manual, Nix Manual, Nixos wiki: Packaging/Tutorial - NixOS Wiki. If I had never created a nix package before I would definitively klick on the Packaging Tutorial Link, as it’s the only one with “Packaging” in the name. And what do I get when I open the page? Links to the Nix Pills, the Nix Manual and the Nixpkgs Manual. What am I expected to do to get the Informations I need? Read this page, the nix pills, the nix Manual AND the Nixpkpgs manual?
Another thing I realised (while writing this comment) is that the wiki is unofficial and therefore sometimes quite poorly written, to the point that it’s stating that it may be outdated/wrong. False information (a.k.a. tutorials that don’t work) can surely be a reason some users don’t stay. I’ve seen that there is a maintainer team for the archlinux wiki. We may also find people to build such a team and make the wiki official? The Manuals could then also become a part of the wiki and I’m sure we could find a solution to be able to present them both as a one pager (for those who can’t miss them) and as separate wiki entries per topic. If we then want Manuals on different use cases we’d have for example one wiki page called “Docker” with different subtitles for e.g. “Nix in Docker” or “building a Docker image with Nixpkgs” (hey that’s already the case!).
One solution I proposed here was -NixOS- code vs wiki vs manual - #14 by SRGOM - having no wiki and manual PRs are triaged separately, this keeps a single source of truth, maintains quality and keeps things versioned.
I hope before replacing the current search pages the ability to sort is added(or the default sort order changed to alphabetical). Not being able to sort the results makes the options search quite a bit less useful than the current tool.
For example, if I am configuring a service, having all the options related to that service grouped together is fairly important. Sorting is even more important when the module supports submodules.
The preview also seems to have some significant bugs. Is that running off the current code? Should I be opening github issues for bugs present in the preview?
We are moving into that direction. Let me explain…
One focus of marketing team is to present information on the website in a way that it can be easily discovered. Be it documentation or something else. But as we can agree documentation is something very important in a project like Nix.
While there is no documentation team currently there is quite a lot of different efforts in regards to documentation. We could wait for RFC 64, where a format / tools are being discussed, to be resolved or we can also move ahead and produce the content that we think is missing for newcomers. This will come in form of guides / tutorials (eg. Build docker images with Nix, …).
Hope this answers some of your concerns. What I think is important that we move step by step (eg. tutorial by tutorial) otherwise the size of the effort needed will wear us down.
I hope before replacing the current search pages the ability to sort is added(or the default sort order changed to alphabetical). Not being able to sort the results makes the options search quite a bit less useful than the current tool.
Sort is definitely possible to add, but we are first focusing on implementing bare minimum and replace current search. What will follow shortly after is an option to drill down your search results. eg. searching for requests should present you with different pythonXYPackages versions that you can search in.
For example, if I am configuring a service, having all the options related to that service grouped together is fairly important. Sorting is even more important when the module supports submodules.
At the time of writing we only focused on having packages search yield better (more relevant) results. We are yet to look at options and how to make that search better.
The preview also seems to have some significant bugs. Is that running off the current code? Should I be opening github issues for bugs present in the preview?
I would wait until the search.nixos.org is going to be announced and then report bugs. Currently things are still in a bit of flux and there are also things that are still planned before we called it a release. Time wise I think we will be have first release in next 2 weeks.
I might argue that having the option search be at least as usable as the current search should be part of the bare minimum. Even if you don’t all the bells and whistles implemented, at least don’t apply a relevance sort to it as you would a package search.
EDIT: After reading this the next day, I realized it may come across more sarcastic than I intended depending on how you read it. @garbas, I want to be clear that it was not my intention to be overly critical and I appreciate all the work you guys are doing. I just wanted to point out that something I felt was important was at risk of being lost as it was looking at that point in time. I apologize if I did poor job of communicating that.
Yeah I understand that it will need the RFC64 to be merged before we can decide on one place for all the documentation. It‘s just a bit confusing to me that the temporary decision is to create another place instead of using the wiki. But I guess I‘ll just accept that and wait for the RFC to be closed in hope that we can then move on to merge all our documentations to have them at one place afterwards.
As long as the smart sorting only puts some „important“ packages at the top and leaves the rest sorted alphabetically, I don‘t see much of a problem. The difference to the old search isn‘t that big.
But I noticed that the new search matches less packages. e.g. wpg will only match libwpg in the new search while it also matches wpgtk in the old search.
On another note: @garbas have you ever thought about adding Github Issue/PR/commit infos to the search? It would sometimes be useful to know if there is an open ticket for a package, or which was the last changing commit, etc. I would really love if such a feature would be in the backlog!
How exactly would that be better than using an existing, mature platform? The only reason Debian is rolling it’s own is probably that it predates the GitHub era. Not that I‘m a fan of GitHub in particular - it’s just there and it works.
I think there is some misunderstanding here. The comment by @Melkor333 is about adding references to GitHub issues on a NixOS search page, it’s not about extending GitHub with functionality we need. The Debian Tracker is also not an issue tracker, it’s about collecting all relevant information of a package in an overview.
Well yeah, actually I already made a thread about exactly that some time ago.
But in my eyes the debian tracker and the nixos search are not far from each other. The nixos search platform could slowly be transformed into a tracker by adding more and more tracking information to it
And given the NixOS search is actively improved the chances it‘ll get some tracking features are higher than the chances somebody creates a specific tracking platform…
I guess any further discussion about this makes more sense in your thread 
