2023-03-23 - Learning Journey WG meeting notes #1

2023-03-23 - Learning Journey Working Group Meeting Notes #1


  • Create a detailed draft of documentation structure


  • Goal: Have a place to put docs

    • Two ways:
      • Decide on structure first
      • What should exist, build structure from that
    • @brianmcgee: Lot of existing docs of various quality, fragmented, hard to know how to put it into a different framework. Easiest might be to start fresh in a single place and port old parts over.
      • @erooke: +1, often find something but can’t remember where it goes.
  • @henrik-ch: What about Learn Nix? Has guides from nix.dev but is a mirror.

    • @infinisil: homepage source builds using nix.dev
    • @zmitchell: First steps is a shell environment, not installation guide, doesn’t feel super organized. We don’t need to be concerned with where the single place should be
  • @zmitchell: What do we want it to look like? E.g. broken down by tutorials/how-to’s, diataxis framework. Should we brainstorm what should exist, or should we look at what we can fill into the categories?

    • @henrik-ch: Basically, top-down or bottom-up? @zmitchell: Yes
    • @brianmcgee: Dev experience should inform us. Tutorials give background, but the main thing is to know how to get things done, should be the on-ramp.
    • @infinisil: Various ways get into it from different aspects, can start from either tutorials or how-to’s, need cross-linking
    • @zmitchell: Should encourage cross-linking e.g. in the contribution guide.
    • @brianmcgee: First time you mention something, should be a link
    • @infinisil: Regarding question: Bottom-up imo, since all the material was created organically
  • @zmitchell: We have nix-book/resources.md at a3b36fa16e75c12aed467c25447bfb5e2650c409 · NixOS/nix-book · GitHub. Let’s go through that to fill out table of contents.

  • Differences:

    • nix shell, only PATH, works with your own shell, for environment with some packages
    • nix develop, hooks as well, only bash, for development
  • @infinisil: nix-shell is stable, flake-stuff might still change

  • @brianmcgee: Flakes concepts are more familiar to more people. If we don’t use flakes we need to explain more things to get people up to speed, e.g. niv instead.

    • @infinisil: Can mention flakes and link to their docs, so users are aware
    • @zmitchell: Not just stability is a problem, but tooling can also be flake-based, e.g. crane rust tooling only works with flakes. Is there a way to call a flake from a non-flake?
    • @brianmcgee: Need to prepare people for what’s out there
    • @infinisil: Beta flake page
    • @zmitchell: Not separate page, but if a page is for flakes, have a banner at the top.
      • @infinisil: Ends up with multiple ways of doing the same thing
      • @zmitchell: I mean for flake-based things that can’t be done another way. E.g. Headings for buildRustPackage, crane (experimental!!)
    • @brianmcgee: Wider question: How to deal with flakes. E.g. decision for Zero To Nix to be flakes oriented, makes it conceptually easier.
      • @erooke: Didn’t we say the opposite, say no to flakes?
    • @infinisil: Let’s not discuss flakes further, we had this in the docs team, decided on stable only
  • @zmitchell: First tutorial: nix-shell -p with a useful package

  • What is step two?

    • @brianmcgee: Two tracks: Ops (towards nixos) or development (towards building)
    • @zmitchell: Let’s pick development
    • @infinisil: shell.nix comes naturally after nix-shell -p
    • @brianmcgee: Focus on getting set up on language tooling
    • @zmitchell: Let’s only pick one language. Maybe not Python, it’s a mess
    • @erooke: My workaround: install python, use python’s env manager. Is the goal to manage everything with Nix?
    • @zmitchell: Only thinking of language tooling, e.g. python and pip. Don’t need to go into more Nix-specific dependency management
    • @infinisil: mkShell, niv pinning of Nixpkgs, how to go from nix-shell -p to same env for everybody for a project
    • @brianmcgee: Also direnv, switch for versions, customization using arguments. How to allow things to be overridden.
  • @infinisil: What about installation? Tutorial or link to homepage


- Installation of Nix
- Start with a shell with some new packages installed in the shell
    - `nix-shell -p <foo>`
- Start a shell with some language tooling
    - Just Python and pip
    - Show how to create a `shell.nix`

Action Items

  • @zmitchell: Talk with diataxis people, planned for 2023-03-29
  • @zmitchell: Didn’t get to documentation structure, put up a PR with documentation structure so we can work on it async
  • @erooke: Find nix-shell -p tutorials and determine the state of them, create and/or find relevant nix.dev (or other GitHub repos) issues