2023-06-26 Documentation team meeting notes #58

Agenda

  • update
  • reviews

Updates

Reviews

ease onboarding of contributors · Issue #333 · NixOS/nix.dev · GitHub

  • closed as completed

Declarative reproducible developer environments by worktheclock · Pull Request #256 · NixOS/nix.dev · GitHub

Add instructions to install nix with a package manager. by loreb · Pull Request #197 · NixOS/nix.dev · GitHub

Nix language tutorial: restructure introduction by fricklerhandwerk · Pull Request #609 · NixOS/nix.dev · GitHub

Change project's self-description by asymmetric · Pull Request #575 · NixOS/nix.dev · GitHub

  • Tagline “Getting things done with Nix” is agreeable

FAQ: why are flakes controversial by fricklerhandwerk · Pull Request #546 · NixOS/nix.dev · GitHub

  • @proofconstruction raised question about how we deal with flakes
    • there are a lot of questions by new users, and no clear communication
    • flakes come up in official channels in many discussions/PRs/issues (anything about shell.nix & reproducible dev environments, anything about nixpkgs pinning)
  • @fricklerhandwerk: we agreed last year that we will focus on documenting stable interfaces given our limited time
    • we have been following that ever since, but it’s not written down in visible places, only in these meeting notes
    • should add this to the maintainers page and contribution guide
  • reviewed and merged

I think the path is fine. You can work on this and pretty much every outside contributor is writing tutorials that are flakes first.

Would be good to have a clean handover/interface between your docs and people then going out into the world of flakes.

PRs welcome, as is adding high quality third-party materials to our recommended reading list.