teaching Nix 3 CLI and Flakes

[fricklerhandwerk]

based on my usability study, newcomers are confused about the purpose, role, and future of Nix Flakes.

• document what works now or work against next major release?
• options
  • support only one and not the other
  • work on different branches
    • related: versioned guides #289
  • present both approaches
    • prepend explanation on history and state of affairs
    • no value judgement, be strictly descriptive
      • our goal is to enable people to learn, not convince them of anything
    • let users decide
      • can take any of the paths or all of them
• considerations:
  • presenting a consistent user experience that is easy to understand
    • trade-off: pruning too much information but may actually increase confusion
  • relying on Nix release schedule
  • maintenance overhead
  • future migration effort for users and documentation authors

Acknowledgements:
@JacklineYim pointed out it would be more intellectually honest and practically helpful to communicate clearly what exactly is going on instead of pretending there are simple answers.
@guaraqe proposed the side-by-side approach.

[olafklingt]

A side by side approach has more overhead than might appear at first sight. For example the cli, It's documentation is mostly done for both versions, but when in other sections of the documentation a cli command is used which version should be used?
I think a prioritization helps to reduce scope of the project.
If there are not enough resources to document everything, I think it is best to mention alternative approaches, and make clear why they they are not equally documented.

[fricklerhandwerk]

A side by side approach has more overhead
[...]
when in other sections of the documentation a cli command is used which version should be used?

Yes, we don't have the resources to do it consistently throughout. But it should be possible for the introductory lessons together with a preface. If we present it well, people should be able to fill the gaps themselves (in practice, or even by contributing to the docs).

[fricklerhandwerk]

• @domenkozar would open branch and subdomain (3.nix.dev) to have a place for them
  • merge or swap once it's released
  • should be best way to prevent users from being dragged into what is not yet released
  • @infinisil @fricklerhandwerk agree
    • consider: may have merge conflicts on release of Nix 3.0
  • @fricklerhandwerk should still generally introduce Flakes on the main branch and explain what's going on
    • right now people jump onto Flakes because they pick up they are supposed to be somehow better or the new way of doing things, but get overwhelmed by bad tutorials or inherent complexity
      • @infinisil Flakes are hard to learn on their own and add complexity
    • @domenkozar it's scary, there is no good Nix language tutorial and no Flakes tutorial, and Nix 3.0 is coming up
      • not blaming anyone, it's hard and takes time to write good material
      • @fricklerhandwerk told by @garbas marketing would rather wait for Nix 3.0 documentation being done before releasing, to have good material right from the start
        • is there even a timeline for release?
          • @infinisil said to be "soon", when ready, but does not look ready
          • have to work incrementally, best effort

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-07-07-documentation-team-meeting-notes-4/20198/1

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/usability-study-session-2/21400/1

[domenkozar]

[Ericson2314]

I left a comment on the tweet: https://twitter.com/ericson2314_/status/1680630061353824256 We should not promote unstable features, or "unstable" doesn't mean anything. Period. I wrote an RFC for how and when to stabilize Flakes, NixOS/rfcs#136. Pro-Flakes people have largely ignored the RFC.

If anyone wants Flakes to be promoted in official teaching material, they should want Flakes to be stable, and they should therefore engage with the RFC or counter-propose something else.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-07-17-documentation-team-meeting-notes-64/30653/1

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/rfc-0136-fcp-a-plan-to-stabilize-the-new-cli-and-flakes-incrementally/30961/5