Closed fricklerhandwerk closed 1 year ago
It's still quite a WIP, but the first few chapters I think are in a decent rough-draft state
stdenv.mkDerivation
. Should be as useful as possible as quickly as possible. Shouldn't go too deep, Nix Pills were scary! Good content but thick.nix-build
. Tree-like structure isn't a great narrative. Cross pollination of topics unaviodable.
Perhaps all that's needed is to eventually host the book at book.nix.dev, and have a link to it on the side panel. I think have a distinct book, seperate from a collection of tutorials and reference material is highly useful, and was a huge success for Rust.
One of the things the Rust book does really well is to go over this foreign new concept "the borrow checker" in a way that is repeatedly addressed through a repetition of examples throughout the material. In our case, the new foreign concept is "the derivation", and I think a similarly structured approach would pay dividends.
This issue has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2022-08-25-documentation-team-meeting-notes-8/21241/1
Yes, what I would like to clarify in general, and missed to ask today, is if we should more clearly separate the Nix Book as tutorial from nix.dev as guides. Because the Nix language tutorial is definitely a tutorial, and the beginner guides for CLI use and all that stuff are also kind of tutorials, but maybe also guides, because they help solve concrete problems.
Should we restructure nix.dev and sort out tutorials into the Nix Book to be really clear about this?
~@fricklerhandwerk~ @infinisil Wow, your note taking is excellent
@jonringer today credit goes to @infinisil - thanks again!
As the one structuring our onboarding journey, I may add first hand experience to this point:
Every time we hire someone, it's hard for them to get onboarded.
The real problem, in my opinion is that package management is a side effect of "Nix as config language with superpowers", as described in std
's "Why Nix?".
So from that angle, a layered explanation that doesn't start with package management, but arrives at package management through fundamental properties of the Nix Language (= derivation
) would go a long way in clarifying things.
This would serve the DevOps use case a ton that makes use of Nix as the repository-spanning configuration lingua-franca (as direct alternative to yaml, json, cue, etc).
Perhaps all that's needed is to eventually host the book at book.nix.dev, and have a link to it on the side panel. I think have a distinct book, seperate from a collection of tutorials and reference material is highly useful, and was a huge success for Rust.
One of the things the Rust book does really well is to go over this foreign new concept "the borrow checker" in a way that is repeatedly addressed through a repetition of examples throughout the material. In our case, the new foreign concept is "the derivation", and I think a similarly structured approach would pay dividends.
My idea has always been to make a book out of nix.dev content, so those two aren't orthogonal.
Having it as a free resource first and a book later optimizes for access to free education.
:100: there should be a book, if we make that a community effort we'll be much faster once we get the initial handshaking done
problem so far has been, with all material, that it is not really focused, therefore not meeting user needs well
In my opinion, it's suboptimal to distribute these four aspects across different projects, but if path-dependency commands us to (temporarily) do so, I would cut it in half rather on the "for work" / "for study" axis.
These are the primary learning situations that a user is actually in at any given moment.
This issue has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2022-09-08-documentation-team-meeting-notes-9/21546/1
@Jonringer looks like you didn't have time to continue working on it. Closing for now. Please get in touch if you get to it again and you'd like to collaborate. :)
@jonringer and @nrdxp work on their vision of a Nix Book (Discourse announcement).
Let us see how we can align goals, coordinate efforts, and avoid redundant work.