- Video conference
- GitHub project board
- Team details
- Past meeting notes
- Attendees: @henrik-ch @pennae @zmitchell @fricklerhandwerk @j-k
- Notes by: @zmitchell @fricklerhandwerk
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.
-
@zmitchell: we want to stay with GitHub and not introduce new tools
- @fricklerhandwerk everyone on the team should have triage access now
- we are labeling some issues and updating the board accordingly
Nix REPL documentation
- improved help command listing. by henrik-ch · Pull Request #7661 · NixOS/nix · GitHub
- talked about different approaches for better documenting
nix repl
-
nix repl command completeness · Issue #7956 · NixOS/nix · GitHub
- @fricklerhandwerk: will discuss this with the Nix team so we can move forward with a more principled approach
-
@henrik-ch will try to do somthing similar to the primops and refactor
nix repl
-
@fricklerhandwerk: make a proposal first, it should outline the change
- this will make it easier for the team to support the effort before investing too much work
-
@fricklerhandwerk: make a proposal first, it should outline the change
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.- @fricklerhandwerk: please get in touch with @asymmetric to coordinate, you could pair or review each other’s work
-
@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
- Tracking issue - re-shape current content into a structure based on Diataxis · Issue #499 · NixOS/nix.dev · GitHub
- we will slot in all content under these four headers.
- we could have a landing page for each section (as a second step)
- some content will probably need reclassifying
-
@fricklerhandwerk: great. just go in small steps to get your changes in.
- maintainers are extremely limited in bandwidth, and reviewing large changes is prone to raising objections
-
@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
-
@fricklerhandwerk: be sure to test on complete beginners before you change the
-
@zmitchell do we have buy in to add things to the side bar?
- @fricklerhandwerk: yes, see past meeting notes
- just go slowly and incrementally
-
@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
-
@fricklerhandwerk: yes, good documentation is expensive
- 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
- it’s also a lot of effort just to get some documentation in
Action items
-
@henrik-ch will improve the
nix repl
documentation proposal- make an outline on how to solve the problem
- @j-k will take a look at Nixpkgs Go and Rust sections
- @zmitchell will keep the team posted on developments around a potential Diátaxis workshop