2023-05-25 Documentation team meeting notes #50

Agenda

  • Brief @roberth on the docs project
  • Review open PRs

Notes

  • @fricklerhandwerk: will prepare contracts until end of next week
  • @zmitchell: @infinisil wasn鈥檛 there last week so we struggled a bit :slight_smile:
  • @maj and @roberth will meet with @fricklerhandwerk and @zmitchell next week
  • (some pontificating on how to approach teaching)
    • @zmitchell: Nix is a bit like Physics, sometimes you have to hide the nasty details to make good process
      • @fricklerhandwerk: Question to @roberth: Should we make Nix be like a spherical cow?
        • @roberth: Yes, e.g. derivations are very messy underneath, but we simplify the explanation a lot
  • follow-up on 2023-05-18 - Learning Journey Working Group - Meeting Notes #9
    • @fricklerhandwerk: Starting from the bottom makes it easier to understand it in my experience
    • @roberth: Depends on the kind of docs, reference docs should be bottom-up, very detailed. For other documentation you can start at a higher-level, e.g. guides are specifically suited for that
    • @zmitchell: Before you can teach something you have to break down the misconceptions, e.g. giving an example where it doesn鈥檛 work, then show why it doesn鈥檛 work. What are misconceptions people have about Nix?
      • Although people might not have a lot of misconceptions about Nix, but rather about other package managers
      • @khaled: Misconceptions around what problems it solves
      • @fricklerhandwerk: Have observed a large number of distro-hopping users coming with assumptions about how GNU/Linux works. They are currently not our target audience though.
      • @roberth: Came from functional programming myself, so I didn鈥檛 struggle much with Nix
      • @infinisil: Also coming from Haskell, which is really well designed, but the Nix ecosystem was hacked on for like 20 years, leading to a lot of quirks
      • @zmitchell: Nix is a lot simpler from a language perspective, difficulty comes from it being blue for everything else
      • @khaled: Lazy evaluation is a little mind-bendy. Another part is Nixpkgs
        • @fricklerhandwerk: Remember spending a lot of time trying to understand parts of Nixpkgs
        • @zmitchell: Overlays are really mind-bendy to new users
        • @khaled: Modules as well
      • @fricklerhandwerk: Cannot fix 20 years of hacking quickly (Nixpkgs Architecture Team exists to fix it slowly though), but we can write down a path to explain it
        • we may want to provide a content map to give users a way to navigate through the different concepts to understand.
  • @infinisil: Giving a brief introduction to the team and nix.dev for @roberth
    • @fricklerhandwerk: Meetings sometimes feel like unproductive chatter, but the point is communicating shared knowledge and dispell misconceptions
      • @roberth: Same experience when writing my own stuff, coming back to it after some years gives you an entirely different perspective. Discussing is good if we also get stuff done outside discussing
    • @infinisil: Feel like we鈥檙e discussing a bit too much, maybe we can scale meetings a bit better
    • @henrik-ch: Enjoyed @infinisil鈥檚 Nix Hour this week, maybe we could also have a docs team meeting like this
      • @fricklerhandwerk: Will consider this. Not sure about publishing that much content this fast, prefer writing
        • @henrik-ch: No need to record, some people might be uncomfortable with it

First version of the document survey table template by henrik-ch 路 Pull Request #560 路 NixOS/nix.dev 路 GitHub

turn anti-patterns into best practices by fricklerhandwerk 路 Pull Request #548 路 NixOS/nix.dev 路 GitHub

  • merged

FAQ: what are flakes by fricklerhandwerk 路 Pull Request #545 路 NixOS/nix.dev 路 GitHub

  • @fricklerhandwerk will make a concepts section and add flakes in there as a first entry