NixOS
Accommodate divnix/nix-book
@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.
It's still quite a WIP, but the first few chapters I think are in a decent rough-draft state
- @fricklerhandwerk: From the beginning we figured it doesn't make sense to bootstrap from zero, so use nix.dev as a start. After attempting essentially the same thing in the past months, it's a huge topic to cover systematically.
- @jonringer: My attempt is to describe 80% of what's needed to use it, data types that are used most of the time. 90% of the time it's just lines and attrs and
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. - @fricklerhandwerk: Tried this with Nix language tutorial, showing what is most often used, try not to overwhelm overwhelm. When giving lecture to people, reading descriptions is fine, but examples need a lot of handholding to help people understand semantics.
- @jonringer: When coming from Haskell not too hard, but from e.g. Python a big hurdle
- @fricklerhandwerk: Keep narrative for now, but have minuscule details to improve the above. It should be superficial enough to do daily work, but also detailed enough so no assistance is needed. 1:1 training does not scale well, existing written material is either too dense or too sparse, and there's a lot of people who don't have anybody to instruct them. Can we collaborate on this?
- @jonringer: Merging is hard, more voices, more inputs/opinions, how it should be approached. It's hard to know what to do after the first
nix-build. Tree-like structure isn't a great narrative. Cross pollination of topics unaviodable.- @fricklerhandwerk: Has a PR with tree outline. If ordered strictly by amount of moving parts, cross-pollination should not be a problem.
- @nrdxp: Every time we hire someone, it's hard for them to get onboarded. But we have lots of engineers to test tutorials. Needs lots of time to refine.
- @fricklerhandwerk: Would like to gather all that feedback? Session notes from my user studies currently being redacted, should be published soon. How to make beginner struggles visible for help with book?
- @nrdxp: Idea: Course material, afterwards discuss with them what they found helpful/not. Would like to help with that.
- @fricklerhandwerk: Please try the tutorial in the PR!
- @fricklerhandwerk: Ideally would be working on a single repository, we seem to have lots of overlap. If we have a common roadmap with clear goal, etc. everybody can do what they can do best. Related: would like goals by the NixOS Foundation board, so everybody can focus on something specific. Oftentimes people don't know about what's happening in the ecosystem. (Nix book is case in point)
- @nrdxp: Originally didn't publish it as there wasn't a lot. @jonringer had a lot of time recently, getting it to a point to share it. All for having it in a single place. Not sure how to structure that.
- @fricklerhandwerk: Take a look at outline?
- @nrdxp: Sounds good
- @jonringer: My attempt is to describe 80% of what's needed to use it, data types that are used most of the time. 90% of the time it's just lines and attrs and
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?
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
- @fricklerhandwerk unfortunately @jonringer and @nrdxp are not here today
- @fricklerhandwerk would like to clarify objectives: tutorials vs. guides
- see diataxis.fr
- problem so far has been, with all material, that it is not really focused, therefore not meeting user needs well
- for nix.dev we have multiple new PRs which are either guide or tutorial
- @domenkozar right now nix.dev is just a top-level collection
- we could have a curated curriculum and next to it a bunch of useful stuff
- structure will emerge once we have more material
- @fricklerhandwerk it's about presentation, we should clearly separate the two types
- also like the idea to have curated core and collection of things
- we can offer people reviews if they want to contribute stuff
- editing the wiki will usually not be replied to
- additional collection can even be just pull requests
- we can offer people reviews if they want to contribute stuff
- also like the idea to have curated core and collection of things
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. :)