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 
