https://github.com/NixOS/nixos-search/issues/506
It seems to be the top issue in the nixos-search repo.
3 Likes
Indeed. Only 8 
, so I added my thumbs up too.
Yes, your summary isn’t too far off. 
Still I’d like to make one last point on this whole issue: You can write documentation in a way that people who don’t actually read it can still go and use it and do their copy-paste-iterate approach.
My suggestion would just be trying that a bit more.
2 Likes
too bad it takes someone popular for us to acknowledge beginner guide shortcomings.
2 Likes
I’ve read answers from many people here, and most seem to be somewhat familiar with the Nix ecosystem.
I’d like to give my two cents as someone who’s tried to learn Nix multiple times, but always ended up shying away from it after a couple of weeks.
As many people have pointed out, I too find the documentation to be confusing. There seem to be at least 3 ways to solve the same problem, Flakes, ‘normal’ Nix and some other, while it is rarely explained to me, why I should use one over the other…
At the same time, I feel like the guidance for beginners is still too technical(?).
I’ve read a whole lot of official and unofficial documentation by now, and I can’t do more than write an EXTREMELY simples Nix file by myself. Whenever I look something up, the amount of information that gets blasted (for the lack of a better word) at you, is immense while still not seeming to be the thing one is looking for (as a beginner).
I hope this doesn’t seem like me being butthurt about being unable to learn Nix. I really appreciate everything the community is doing and would like to become a proper part of it sometime, so that I can give back by contributing in some way.
But at least for the time being, I feel like I’m stuck at the very beginning, without a way to make any meaningful progress.
7 Likes
Yes you are spot on, but my feeling is: in spite of this being a long thread already, I am not sure if we have reached anything resembling a consensus on the two main things:
-
What exactly are the present shortcomings?
-
How to create an actually effective onboarding experience for newcomers that eliminates the shotcomings?
In one of my posts above I said we might need some brainstorming. That wasn’t just a joke. To me a video like that is actually really valuable information because you have a free and natural live recording of a fairly competent user approaching your piece of software and trying to make sense of it. So I’d say, naturally I would wanna learn from seeing that. It’s almost like you are getting a single piece of free experimental data.
Because the current stage were people are left on their own is basically what @4761 has said:
But at least for the time being, I feel like I’m stuck at the very beginning, without a way to make any meaningful progress.
I know that all too well. And I might not even be past that stage myself.
Maybe we should team up and see if we can find systematically the pain-points that get people stuck in that place?
2 Likes
I think @fricklerhandwerk did some user tests with simple usecases:
- download and install nix
- install a package
- open the program in the package
IIRC most got confused by the homepage. There have been multiple threads and issues about it
Those two topics have suggestions within them and related topics that can result in a PR for the homepage, which IMO is the first step. The homepage is probably an important entry point for newcomers. If it isn’t clear, it will turn away new users It isn’t clear and turns away potential new users.
I do not know if there is reluctance to change it, fear of doing so (“I don’t know what this is, so how am I supposed to know what to write?”, “is only the marketing team allowed to change this?”, and similar feelings), or inability to do so (what in the world .tt? can only nix users contribute with the nix-shell requirement?, etc.), or all the above.
3 Likes
Perhaps a beginners Nix book similar to “Learn You a Haskell for Great Good!” or “Clojure for the Brave and True” could help. Or is Nix too vast to pull something like that off?
I guess also getting some hands on resources like https://exercism.org/ could help, but that focus would be mostly on the programming language.
Personally I use Nix in so many different ways:
- System/Environment
- Managing system level configuration and software for Linux machines via NixOS
- Managing user level configuration and software via Home Manager
- Using NixOS-WSL to generate custom WSL distributions
- Projects
- Maintain project level dependencies via devshell and flakes
- Configure pre-commit hooks, formatters and other checks
- Generating files
- CI/CD pipelines
- Terraform via terranix
- Build docker images
- One-offs
- using nix shell/run to execute software I use rarely (comma can be used here for even more convenience)
I know there are a lot of other ways to use it like creating modules/profiles for the workplace where teams can share part of their setup. You can build VMs. You can package software in bundles that can execute anywhere. Those are just things that come to mind.
Braindump of topics:
- Nix the language
- Nixpkgs
- Nixpkgs lib
- The module system
- Packages
- NixOS
- Shells (dev shells)
- Direnv integration
- Declarative project environments
- Interactive adhoc/oneoff shells
- Home Manager - manage user level configuration
- Flakes
- Intro to flakes and the new CLI
- flake-parts
- treefmt-nix
- pre-commit-hooks.nix
6 Likes
Thank you @nixinator for summarizing the trajectory of the video and some key points!
That’s still what I am doing. I’ve seen so many small projects pop up around Nix and being abandoned quickly that I’m very cautious to depend on any third-party tool. I still haven’t even started using home-manager 
I know that and devenv have a strong backing by the community, so this feels more like a me-problem.
Not verbatim, maybe, but after reading the docs it’s striking how similar the format is to flakes, and how its approach could solve the use-cases that currently are served by user profiles, system-manager, nix-darwin and home-manager.
With all the constant issues we have around flakes and the fact that it’s still uncertain how to even reach feature parity with “old-school” Nix in some regards, I’m wondering whether it’s time to re-think the “one file for everything” approach for flakes.
3 Likes
As someone who installed Nixos about 3 weeks ago, I read this thread with great interest. For some context, I’ve worked in IT for nearly 30 years, sysadmin, developer, devops, in over 20 years of Linux use I’ve had desktops and servers of Redhat, Fedora, Debian, Slackware, Gentoo and others. My nephew (also dev/devops, and he knows functional programming) told me about Nixos and so I downloaded an ISO and installed it.
My experience has taught me to be cautious, so I went vanilla, no flakes, no Home Manager, just pure configuration.nix. All good. I read a bit of documentation, the install went OK, but it has to be said that I didn’t install anything except X and Plasma so I ended up with a very simple config file. And like many people, I was left without a functional profile. Neither a system profile nor a per-user one. Lots of dead symlinks. A lot of googling and reading and being confused and I found out that oh, you don’t really need a profile any more, because channels, apparently … and now I know about two sets of tools, the (deprecated??) nix-* and nixos-* and the newer nix tool. Remove the dead symlinks and find out that (some?) nix-env commands recreate it … broken. Jesus wept. So I figured out how to fix all the broken symlinks and I think I have a profile? Does it matter?! It seems to allow me to give my custom config to some daemons / services / X and KDE userland stuff.
My laptop is multi boot, so I was under no pressure to make it work quickly. The plan was to start installing the stuff I use and see if I could get a usable system. Which I did in 3 or 4 days. I must have spent nearly a day screwing around with bootloaders 
Nixos has been my quotidian OS since then.
As a long time Linux user, my environment is pretty customised. It’s mostly in a git repo and I have Ansible playbooks to do some of the tedious bits, so I haven’t converted my existing customisation to anything nixy yet. And this is where the trouble really starts …
Just trying to get packages installed, started at boot and with a custom configuration involved a huge amount of googling because the documentation either didn’t answer any of the questions I had or I couldn’t find it. And neither could Google because I ended up reading about a lot of 3rd party stuff. The same quandary as everyone else … do I embrace Flakes? Is Home Manager enough? Should i shun 3rd party tools altogether? Why does the base OS leave such problems to be solved?
So many of the problems I needed to solve and googled for only had solutions using such 3rd party tools. I have managed to solve most of my problems now, but it’s been a savage struggle at times. Including, but not limited to, Libreoffice’s environment variable requirements, vim plugins that need python in a venv, trackpad gestures (God bless you libinput-gestures) and more.
I actually really like Nixos, it’s a great concept and it will be my main OS for a while. But then I loved Gentoo for 10 years hehe. And Slackware for another 2 or 3. I was motivated to solve my problems. I have written Gentoo ebuilds, Slack packages, perl modules, python packages … and I have to say the idea of writing a nixpkg is the most fearsome prospect yet
Two questions if I may:
Should I start using Flakes or Home Manager?
Should I make posts about some of the specific weird problems I’ve solved and if so, where?
Cheers,
Rich
9 Likes
@octomancer: It sounds like you have experience, patience and a desire to learn.
You should definitely check out Eelco’s thesis which explains in detail how the nix package manager works. Once you understand that, all of the weird parts of NixOS will make more sense.
My two cents about the whole issue being discussed here is that we have fantastic documentation for people who are willing to slowly learn, but absolutely awful documentation for people who want to leverage our tools quickly with a shallow understanding.
1 Like
Make the tool more “stupid” friendly.
Docker and Flatpak are easy to use and you don’t even need to read any documentation to run something.
5 Likes
I had a similar question as you, @octomancer , when I started. Got told to not worry too much and now I haven’t yet used either of these. Though I think I’ll start using flakes this month.
For the home user, I believe flakes solve problems I don’t have (installing exactly the same software from a single unchanging version of Nixpkgs on two different machines) and introduce problems I don’t want (getting weirdly opinionated about my Git commit workflow, downloading lots of extra copies of Nixpkgs, distracting abstractions involving my system architecture that seem way overengineered for a single-machine use case). Would not recommend unless you know what you want out of it and are willing to put up with a double scoop of nonsense. Thank goodness the old channels-oriented stuff isn’t deprecated yet; it’s exactly the abstraction I expect from a Linux package manager.
Home Manager, on the other hand, is very unintrusive. It works as advertised, and you can roll into it incrementally. I started out just with a list of packages in my Home Manager config and have, over several years, started migrating more and more dotfile contents to it. Would recommend; it’s easily reversible if you encounter problems with it (but I never have).
6 Likes
If this is relevant to the geohot video and not just a preexisting desire that’s being dumped here because this is turning into the ‘general usability issues’ thread, what specifically did geohot try that the tool should have done something different with?
For example, when geohot ran nix run mediawiki, was the issue that the tool was not ‘stupid’-friendly enough? If so, what should it have done? (docker run mediawiki launches a container image containing Mediawiki and enough of a stack to usefully run it, because Docker is a container tool and not a package manager. Flathub doesn’t contain a Mediawiki, of course, so flatpak run org.mediawiki.MediaWiki or whatever can’t be expected to work, and Flatpak scores as just as easy as Nix on this metric.)
If that is an unlucky example, can you present any different example from the video in which geohot did the right thing and it was the tool that needs fixing?
1 Like
This is informative and useful, thank you @rhendric
Backout-ability is important, what you have said means I’ll give HM a try and leave flakes for now. I need to install some software that is not in nixpkgs. I thought flakes might help with that, but those downsides you point out would irritate me too. I think I will put my efforts into nix-shell and/or nix repl and try and write my own packages. Which of course leads to more questions like, do I embrace devenv.sh … whatever that is
Keep it simple! There are a lot… a lot… of blog posts evangelizing someone’s own pretzel Nix-fu. Even the well-regarded resource Nix Pills takes a from-first-principles approach that largely ignores the groundwork that Nixpkgs lays for you.
For a non-flakes introduction that IMO hits all the right notes and doesn’t try to sell you on any tools you don’t need, Building a Nix Package | Karim's Blog is a great start.
If you go looking for more, here’s a massively oversimplified rule of thumb: if something purporting to teach you how to write your own packages doesn’t at some point introduce the arcane invocation
nix-build -E 'with import <nixpkgs> {}; callPackage ./default.nix {}'
turn around and find something else. That’ll cut off 80% of the problems.
Good luck!
5 Likes
Thanks to everyone who replied. I will try and read phd-thesis.pdf … at some point. I will try Home Manager and leave flakes for now.
Speaking to the main topic of discussion here, I did find the documentation pretty difficult to navigate, it was not at all obvious what the most valuable things to read first are.
The broken profile after installation led me into maze. For quite a while I was wondering how my system wasn’t completely broken until I found out about channels. The Nixos documentation didn’t do anything to dispel my confusion. I have to say that for the distro toolchain to leave a fresh install in that state after 10 years as an OS and supposed maturity is sub-optimal.
The profile thing also led me to learn more about the nix-* and nixos-* tools and the new nix tool, as I’ve said. This was another maze. Are the older tools deprecated?
A lot of the information I used came from the Nixos Wiki and forum posts. The Wiki in particular was very good on those common niggly things, like blacklisting nouveau and using the nVidia non-free driver, the obscure requirements of LibreOffice and some other stuff that most distros have a page about because they’re all common, hard to figure out things to do. Actually, I think most people just link to the Arch Wiki now
I caught the tail end of the Python 2 → 3 tension, about a year or 2 until Python 2 was deprecated (Jan 2022??) I feel a bit like that now, stuck in the middle between nix and the older tools, between HM and flakes and … ??
I’m too long in the tooth for any of this to be a deal-breaker. Just saying that as a newbie to Nixos, even with a decent amount of experience, I would have to agree with those who say the documentation could do with an overhaul hehe.
1 Like
LOL thanks.
I’ve seen that nix-build incantation a fair bit in docs and forum posts already. I get the impression I should get to grips with Nixpkgs before complicating the issue. Seems reasonable. To paraphrase Desi Arnaz, Lucy! You got some readin’ to do!
1 Like
I haven’t seen the whole snippet, but based on what I’ve watched and the comments people made here’s my 2 cents:
There’s many people I convinced to use Nix, but at least equally as many who tried it but got off of it sooner or later. Naturally everyone’s reaction and experience was different, but what was consistent, was that those who stayed with Nix were patient, read through the materials I sent to them and really tried to understand Nix from the fundamental levels.
Those in whom Nix left a sour taste, however, were people who just experimented around and tried to go with the flow and figure stuff out as they went. This obviously does not work with Nix, especially with people who go in with the mindset that “I’ve been using Linux for years, surely it can’t be that different”, and the poor documentation and onboarding experience does not help.
While I truly root for Nix and hope it becomes the de-facto standard, it will never do so, so long as this is the experience that those “experiment-ers” get to go through, as hardly anyone, especially in this day and age, wants to “learn” to use the computer.
10 Likes