2023-05-25 - Learning Journey Working Group - Meeting Notes #10


  • Hired editorial lead, waiting for feedback
  • Talk about suggestions in @fricklerhandwerk’s post
    • 2023-05-18 - Learning Journey Working Group - Meeting Notes #9 - #2 by fricklerhandwerk
    • Essentially suggesting bottom-up instead of top-down
    • Let’s read this and then discuss it
    • @infinisil: Discussing it won’t help, reference is needed, tutorials are needed
    • @zmitchell: Yeah, at some point we just have to agree on a path and take it, but one thought:
      • Building up a single project makes it hard to show certain corners of Nix
      • The Rust book instead builds up knowledge over time rather than building a project over time so it doesn’t have that problem
    • @infinisil: I like the building up knowledge idea, then each tutorial should be more self-contained. But can have multiple tutorials, main one to build up knowledge, another one for a project
    • @zmitchell:
      • nix-shell -p tutorials stays the same
      • shell.nix one is self-contained
      • Python dependencies one might be too specific
    • If we’re going for the self-contained one, we can do more polyglot ones, showing multiple languages
      • E.g. like https://floxdev.com/docs/getting-started/install-flox/ where you have tabs to pick approaches
      • @infinisil: Knowledge shouldn’t be under tabs, should be general, but maybe examples could be like this
      • @zmitchell: Maybe a flat list of common builders, link to the nixpkgs manual for more details and more complete listings
      • @henrik-ch: The flox example is very good, maybe a too high bar, too many things. Maybe we can just write a bunch of tutorials and then tie it together more afterwards
    • @khaled: More important is giving an explanation why the approaches are different, what the packages do, how the paths get assembled
    • @infinisil: Agree, instead of e.g. saying “to use cmake add cmake to nativeBuildInputs”, explain setup hooks, how to use them, how they work, how to inspect them
    • @henrik-ch: Let’s start with Python to not lose ourselves in branching
    • @zmitchell: Maybe we need a tutorial just for PATH, what software is available can be magical. This way we can explain stuff like setup hooks, nix-shell, and Python as well
    • @khaled: Explain general things, use language-specific stuff for examples
    • @infinisil: Sketching a path tutorial issue: Learning Journey tutorial: `PATH` and `PATH`-like variables · Issue #571 · NixOS/nix.dev · GitHub
      • @infinisil: Note that there’s not much PATH-specific stuff in Nix
    • @khaled: More generally environment variables, too detailed for a PATH tutorial?
      • @khaled: Managing environment variables is the more general concept
      • (…)
      • @infinisil: Filesystem and environment variables are both unix process concepts, but most people have a good intuition about the filesystem, so environment variables should still be covered
      • @khaled: Filesystem would be interesting too, where Nix puts stuff, etc.
      • @infinisil: Many people might have the intuition that e.g. /bin is for packages, but really anything works if PATH is right, could be hashed paths, leading to Nix
      • @khaled: Important idea is that Nix can be for any language
    • @zmitchell: PATH tutorial should be about PATH-like environment variables, don’t explain environment variables generally
    • @infinisil: Do we really need a PATH tutorial?
    • @henrik-ch: Let’s just write it and figure out later where it goes

Action items

  • @zmitchell: Create a tracking issue for the set of a tutorials we’ve decided on
    • This will be the source of truth for which tutorials we’ve decided to work on for easier lookup
  • @zmitchell: Create issues for each tutorial we’ve decided on, link in tracking issue
1 Like

Tracking issue for tutorial series: Tutorials overview · Issue #572 · NixOS/nix.dev · GitHub