The reference manuals are not for reading, but for looking things up. If you’re referring to tutorials and guides nix.dev – yes. Learning has a cost, and Nix requires learning a lot because it does many things differently than what one may be used to, and also not always consistently due to how we arrived at today’s state of affairs.
We, the documentation team, are dedicated to fixing that. Please be patient with us. I expect it to take on the order of years to become a smooth experience. It’s getting better by the day, but until then you can rely on the extraordinarily welcoming community where many people are highly knowledgeable and help out whenever time allows.
Yes. We only recently got to the capacity to make substantial changes, and there is a lot of material to go through. I’d appreciate if you proposed changes with pull requests. There is a good chance they will get merged quickly if they are fairly small, uncontroversial, and follow best practices.
That FAQ was never well maintained. We know it’s a problem, and there is work in progress to clean that up step by step. It will take time though. I expect to see tangible improvement of first-week onboarding by the end of this year. There are lots of details to take care of.
The best you can do to help is put in your time by figuring things out and fixing documentation as you go, or to support the documentation team financially on OpenCollective. We especially need paid maintenance because then we can get work done that volunteers will never take on or finish. This has already allowed us to improve the contribution process, and provided capacity to accommodate work done by volunteers, which would also otherwise linger indefinitely.