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

zmitchell · March 24, 2023, 3:56pm

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

Video conference
Team details
Attendees: @zmitchell @brianmcgee @infinisil @henrik-ch @erooke
Notes by: @infinisil

Agenda

Create a detailed draft of documentation structure

Notes

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.
- @infinisil: Should we focus on tutorials/how-to’s only
- @brianmcgee: Difference between learning/understanding oriented?
  - @zmitchell: See https://diataxis.fr/ and About explanation - Diátaxis
- @erooke: How was nix-book/resources.md collected? Not only official resources?
  - @infinisil: Anything @fricklerhandwerk could find on the internet I imagine
- @zmitchell: Maybe starting with nix language is not the best to get up and running
  - @brianmcgee: Writing your own packages is in my experience like 3 months into learning Nix. Start with familiar stuff. Package management at a high level, how packages work.
- @zmitchell: Example I was thinking of: Add new dependency to an existing package, buildInputs, shell. A package in a global environment or a shell?
  - @infinisil: Shell sounds better
  - @brianmcgee: nix-shell -p, what it does
    - @erooke: nix-shell or nix shell
    - @zmitchell: Or nix develop?
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: Can use flake-compat
- @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
  - @brianmcgee: Maybe not mention flakes at all then
  - @infinisil: We can have a one-sentence mention
@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
- @brianmcgee: Let’s have a tutorial

Tutorials

- 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