2023-03-30 Documentation team meeting notes #37

Development Documentation
1

Agenda

  • check the board for important issues
  • unblock progress where needed

Notes

  • updated @henrik-ch with tips on debugging C++ code
  • started looking at the board
    • @zmitchell: we want to stay with GitHub and not introduce new tools
      • use tracking issues: parent issue with todo-list under it
      • We can add a tracking label to make issues tracking issues.
  • @fricklerhandwerk everyone on the team should have triage access now
  • we are labeling some issues and updating the board accordingly

Nix REPL documentation

Backlog grooming

  • @fricklerhandwerk: taking lead in Nixpkgs manual maintenance is still an open item

    • needs delineating into different areas so that the responsibilities can be shared
    • @j-k: what would it mean to take ownership of a piece the manual?
      • @fricklerhandwerk: example: the Nixpkgs manual section on Python (see last meeting notes)

  • @j-k mentions choice between discourse and matrix for asking questions

    • it’s helpful being on discourse for traceability.

  • @j-k could imagine working on buildGoPackage and Rust as documentation sections.

  • @pennae: we should break up the large manuals into smaller pages

    • if we improve the content and not searchability, it won’t help users much
    • @fricklerhandwerk: agreed. we can still work on contents independently

  • @j-k: if were changing the manual (content and structure), can we keep existing links working?

    • will the new copy be versioned, so that links can keep working?
    • @fricklerhandwerk: redirects live in a different repository
      • do use them to keep URLs working!
      • has to be approached on a case by case basis

Learning Journey

  • @zmitchell: in lieu of creating a whole TOC for nix.dev, we are making four main categories
  • @zmitchell ephemeral shell environments will be our first tutorial
    • @fricklerhandwerk: be sure to test on complete beginners before you change the nix-shell tutorial
      • it already has been tested and improved based on feedback, it’s likely to get worse without a systematic approach
      • Usability study session #8
  • @zmitchell do we have buy in to add things to the side bar?
  • @zmitchell: Daniele Procida offered to run an in-person Diátaxis workshop, possibly in the UK
    • @ron offered support with organising a location
  • @j-k: do we have a way to mark how advanced we are progressed in terms of user study against the specific tutorial/guide?
    • @zmitchell: having this would discourage suggestions
    • @fricklerhandwerk: knowing what is worth improving on is good, currently few people have overview
      • low hanging fruit vs. things that are hard to improve and easy to deterioate
    • @zmitchell: we don’t want to gate it - not necessary to conduct a usability study to do any changes to a document.
      • it’s also a lot of effort just to get some documentation in
        • @fricklerhandwerk: yes, good documentation is expensive
          • but adding something where there is nothing can be fairly easy, depending on subject
          • just make sure to have more eyes on it. you won’t submit code that’s not tested, don’t do it for documentation either
      • could only state date of most recent usability study.
      • @fricklerhandwerk: when you do a usability study, open an issue to track it
        • sit down with beginners and see how well the material does with them.
        • remote sessions work well
        • also helps getting beginners to Nix

Action items

2 Likes