2023-03-21 Documentation team meeting notes #34

Development Documentation
1

Agenda

  • identify topics for break-out sessions on project board (15 min)
  • break-out sessions (20 min)
  • reconvene, report, assign follow-up tasks (20 min)

Notes

  • @asymmetric reached out for a status update to ryantm about nixdoc. Could talk about this today, how to unblock it
  • @asymmetric has felt the frustration of being the only Nix person at a company, and having a hard time at spreading the good gospel due to lackluster documentation
  • @fricklerhandwerk: Should be able to use tutorials as lecture notes for trainings
    • then ideally bring the feedback and contribute improvements based on experience
  • @brianmcgee: At first you just want to use Nix, but it’s hard for people to find the material they need
  • @fricklerhandwerk: Fewer people than expected today, let’s only do two breakout-rooms
    • look at the project board to filter for topics

Potential how-to guides working group

  • @brianmcgee and @fricklerhandwerk consider to start a How-to-guides curation workgroup
    • @brianmcgee: Documentation needs to be focused, it shouldn’t describe too many ways to do things.
      • Documentation is often too dry and theoretical.
    • @fricklerhandwerk: Tutorials to build up knowledge, how-to guides for doing specific things.
      • Do we have the resources to comb through all of the how-to guides around the web and curate and centralise that?
    • @asymmetric: Overlap with the learning journey workgroup?
    • @brianmcgee: Learning journey influences how-to guides, mostly in this order.
    • @zmitchell: IMO how-to guides fall entirely under learning journey.
      • Everybody has a different entry-point.
        • Computing beginners might start with tutiorials.
        • People with a lot of experience might go straight to how-to guides. Some people might go straight to explanation-type docs.
    • @brianmcgee: Difference between what’s a Nix and what’s a Linux problem. Bugs are often mis-attributed.
    • @fricklerhandwerk: How-to guides can require knowledge, can link to tutorials, and the other way around too.
      • If we notice people struggle with something, let’s write how-to’s.
    • @zmitchell: We can do these things concurrently.
      • Let’s not have an explosion of working group.
      • Logically separate tasks, but the same main problem.
      • Just narrowed down the scope for the learning journey group. We don’t need to formalize another working group.
  • Agreement: Should split more if we have more people, not now

Project Board

Split: Nix repl

@brianmcgee, @henrik-ch, @infinisil

Split: Permissions, board structure, licenses

@asymmetric @olaf @zmitchell @fricklerhandwerk

Notes from the GSoD draft