strategy to bring together existing material

[fricklerhandwerk]

• proposal:
  • migrate individual articles from NixOS Wiki and nix.dev, sections from Nix and nixpkgs manuals into central repository
    • take care of properly attributing authors
    • ideally including full history
    • delete original after pull request merged
      • reroute at original site where appropriate
  • announce ways to "promote" new or foreign material, see discussion in team meeting NixOS/nix-book#2

[fricklerhandwerk]

• @fricklerhandwerk assuming we continue working on nix.dev, how would @domenkozar imagine this going?
  • @domenkozar adding tutorials one at a time, that's easy
    • flakes are more problematic
      • opposed to documenting things that are not stable
• @infinisil maybe we are planning too much up-front?
  • @fricklerhandwerk the outline is like a vision we should orient around
    • @domenkozar still need incremental steps to implement it
      • did not want to have such an outline to not make the impression of being incomplete
    • evidence shows it's enormously effective to present bird's eye view at every level of abstraction
    • my vision for the book is to guide people into the ecosystem
    • @infinisil we can have that, but not expose that publicly
      • keep it around as an issue and use it as a guide
      • @domenkozar agree, showing it to the user will just make it look unfinished. users should not bother with things that don't exist
        • actually started that way but people complained
        • @fricklerhandwerk good that we talked, would not have known otherwise
      • have a public version that only covers what's there
• @fricklerhandwerk what about migrating material?
  • @infinisil nix.dev/Nix Book should be curated, where the material comes from should not matter
    • @domenkozar agree
      • more important (possibly hardest) question: how do you pick what to write next?
        • tried different things, such as asking on Twitter
        • was surprized but what people came up with, usually not what I thought
        • when deciding e.g. writing a Nix language tutorial, researched all existing material and trying to bring that together
          • never copied anything directly (also, but not primarily, due to licensing issues)
          • @fricklerhandwerk same here so far
        • was clear that it would be a multi year process
          • will still be even with this bigger team
      • Wiki is a good place as a uncurated dumping ground
        • noticed that people document weird quirks
          • do not want them in a tutorial
    • nix.dev should then be just learning articles?
      • @fricklerhandwerk yes, tutorials and how-tos. reference goes to manuals. we also need explanation, this is severely lacking

        • @domenkozar have a long-standing issue Concepts #139

          • @fricklerhandwerk this should be covered by Document what Nix *is* nix#6420, but that shall go into Nix manual
            • @domenkozar not exactly the same
            • in general, we should lay out all the work in progress not to step on each other's feet
              • centralization is one of the team's goals anyway

[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

[fricklerhandwerk]

I contacted the authors of nix-tutorial.gitlabpages.inria.fr and invited join the next meeting to discuss how we could work together on learning material.

[fricklerhandwerk]

@GuilloteauQ @adfaure @mpoquet @jojothan @augu5te from INRIA (authors of nix-tutorial.gitlabpages.inria.fr) joined the meeting today.

• @adfaure tutorial aims at PhD students working on reproducible experiments in HPC
  • two distinct threads of work: this tutorial and deployment tool for NixOS
  • @GuilloteauQ trying to explain how we use Nix on the team
    • @fricklerhandwerk would it help introducing your team members to Nix through nix.dev?
      • @GuilloteauQ we know our contents and can work with it from the top of our heads
      • @adfaure Nix is not accepted by everyone from the beginning, the tutorial is also a way to explain its benefits and convince people to get into the reproducible software methodology
        • want to make tutorial better for beginners, i.e. researchers in computer science who do not know Nix
        • we could explain better who is the target audience and what we're trying to do
      • what about merging introduction to the basic use cases into a central place?
        • @adfaure the material is under Creative Commons, it's not a problem if you used it
          • we need it to be self-contained in one place, as use it for presentations
        • @infinisil can imagine having a track for scientific work in the central documentation
        • @graham having done a lot of training sessions, understand the need for stable material
          • can imagine duplicating material on nix.dev
          • @fricklerhandwerk would like to reduce potential confusion and impression of duplication
            • @adfaure could make clear the target audience and lead beginners to nix.dev
            • we can at least discuss to align contents and teaching style and continue maintaining them in parallel
              • @adfaure @GuilloteauQ agreed
              • will stay in touch on GitHub

[nixos-discourse]

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

https://discourse.nixos.org/t/2022-07-14-documentation-team-meeting-notes-5/20341/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-3/21401/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-1/21398/1