# 2023-07-06 - Learning Journey Working Group - Meeting Notes #16

Development Documentation
1

Agenda

  • group-review of tutorial outlines

Notes

  • discussion about nix.dev#596 (contribution guidelines)
    • producing outlines first, in a state where other contributors can pick them up and work on them with minimal questions

Group reviews

  • add outline for trivial builders tutorial by brianmcgee · Pull Request #623 · NixOS/nix.dev · GitHub
    • determining/clarifying what is meant by “shell environment”; declarative or imperative?
    • need more detail on what ‘Process X’ is
    • @roberth: the purpose of this tutorial is to teach the user to use any trivial builder, so maybe we should just pick one
      • writeTextFile is deceptive; very simple but last-resort, and we want to teach best-practices
      • pkgs.format has writers for TOML and so on; we should prefer to use those if Nix is aware of the format we need, otherwise use writeTextFile
    • we should avoid leading the reader into trouble; these tutorials should demonstrate the “happy path”
    • @roberth: writeScript creates a single file in the store, but not a /bin/ directory; this is problematic when you use it as a buildInput, because buildInputs expects packages.
    • @roberth: symlinkJoin has some issues, prefer buildEnv, which checks for collisions

Action items