In reply to @9999years:matrix.org
this is the sort of connective tissue that's missing -- all the information is there, but users have a hard time finding it, and part of the reason for that is there's so many places to look for any given piece of information

In 2022 I started with exactly that assessment (which I still share) and with Eelco’s blessing and Tweag’s funding started this: https://github.com/nixos/nix-book

It turned out not to be that simple at all. The ecosystem is too large, the spectrum of use cases too wide, and the details too messed up to just sit down and vomit out how to use it properly and then wait for others to fix the typos. In fact, there have been multiple attempts by different people: https://github.com/NixOS/nix.dev/issues/454

Apart from the initial literature survey, I ran a a small usability study: https://discourse.nixos.org/t/usability-studies/21404 and evaluated the community polls: https://discourse.nixos.org/t/2022-nix-survey-results/18983

When the documentation team was founded the current strategy evolved based on the following considerations:

• nix.dev existed and was the highest quality overview resource out there, the Wiki existed and had the broadest coverage with varying quality - we shouldn’t start from scratch, also for discoverability purposes, so the book idea was dropped in favor of eventually developing nix.dev into that book eventually, incorporating useful bits from the wiki
• the system surface was enormous and messy, so improving everything at once under a somewhat consistent paradigm was (and still is) impossible. We had to focus on a meaningful and most impactful subset
• some things have to be figured out how to even use properly, or even fixed in the code before one can write any documentation. And before writing a tutorial or guide, one needs proper reference documentation. Often that’s lacking, we’ve experienced that for every piece we worked on.
• the most important part for user retention is onboarding and contributing. The only thing usable in isolation is Nix itself.

So this is what we did and are still doing, and we’re quite far advanced with improving the documentation relevant for the first couple of weeks using vanilla Nix. I don’t have the numbers to prove it, but from anecdata and heuristics about the types of questions asked on Discourse, I think we managed to substantially reduce the average initial onboarding time and fraction of people who give up before concluding that.

And even that took what feels like forever, because we ran into many obstacles that relate to governance issues. The first impressions are highly exposed material and so I have to get change proposals past people who have authority over the pieces in question. That’s another reason why we focus on nix.dev more than anything else: the documentation team has free reign over it (within the constraints of not breaking things that already worked for people).

Which means that still, NixOS and Nixpkgs documentation have barely improved in the meantime. We here know all the issues with it, but dealing with them takes time that’s taken away from the original mission. We’re trying to balance that, because not supporting attempts at contributions is of course frustrating for everyone.

What we really need are dedicated maintainers for the various sections of the Nixpkgs manual, all of the NixOS manual, and ideally editors for the (upcoming new) Wiki. This stuff is up for grabs, and I’d definitely recommend org owners to hand out commit bits to anyone who demonstrates they understand and subscribe to the general direction we’re taking. So far no one stepped up, and those who considered, reconsidered again after dipping their toes into the intricacies of the stuff actively being worked on.

We first have to get the basics right before piling stuff on top. There’s already way too much stuff piled up, and the basics are still not in a great shape.