- Video conference
- GitHub project board
- Team details
- Past meeting notes
- Attendees: @infinisil @roberth @zmitchell @fricklerhandwerk @henrik-ch @proofconstruction
- Notes by: @infinisil
Agenda
- progress report
- distribute tasks to project contributors
- managing reviews
- if time left: reviews
Progress
-
@roberth: No updates about the team thing from last Thursday
- What should we ask teams to do?
- @fricklerhandwerk: Subscribe to PRs touching docs and review
-
@infinisil: What about using something like Auto Assign Reviewer by Files · Actions · GitHub Marketplace · GitHub to encourage more people
- @fricklerhandwerk: Tried it on the Nix repo, only worked on upstream branches
- @infinisil: I think figuring this out would be great to get more people to get pings for files
- @fricklerhandwerk: Goal is to get more people to look at docs and maintain them
-
@zmitchell: (brief summary of learning group WG progress)
- Will set up a directory in nix.dev to put tutorial skeletons for reviews
- @henrik-ch: Could work on a separate branch just for the outlines
- Could also get previews with cloudflare directly
- @fricklerhandwerk: Can use https://github.com/NixOS/nix.dev/blob/181fdc6cedb951f1c9b39e8ec2d993e3c50bcec5/CONTRIBUTING.md as a basis
- Will set up a directory in nix.dev to put tutorial skeletons for reviews
-
@fricklerhandwerk: @maj unfortunately cannot carry responsibility for editorial lead anymore for personal reasons
- Will do hand-over of work done so far in the next days
- @zmitchell: @maj already provided valuable input to the LJWG
- Biggest challenge the editorial lead was supposed to help solve: How to process all the work going into the project?
- We have only extremely limited maintainer time, that’s the bottleneck. Have to either reduce costs of maintenance (it was the purpose of designing an outline) or increase capacity (essentially upskilling).
- Alternatives:
- @fricklerhandwerk: We now have some people who can spend some time on narrower tasks, could adjust project goals to that
-
@henrik-ch: Could keep @roberth for longer
- @fricklerhandwerk: And focus more on infrastructure issues
-
@zmitchell: Have existing volunteers start with the migration of the Nixpkgs manual material. Give primer on Diataxis and how to categorize it first.
- @henrik-ch: Related to documentation survey
- @fricklerhandwerk: Classifying and moving material are different but related, one leads to the other
-
@fricklerhandwerk: Triaging PR’s would be useful
- Tell people to look into things and become more knowledgeable in them
- Collaborative reviews first, increase level of autonomy over time
-
@zmitchell: Split up Nixpkgs manual into individual pages. @pennae is most equipped for that, could support that with funding
- @fricklerhandwerk: @roberth could review that work, it would help make progress
- @henrik-ch: Split-up sounds good, could do it at the same time as categorization maybe
- @fricklerhandwerk will think about it and make a decision
- Will do hand-over of work done so far in the next days
Tasks for paid contributors
-
@zmitchell: Categorizing Nixpkgs manual material
- @henrik-ch: Same thing as documentation survey work, which I’m doing, but taking a long time. Help welcome
-
@zmitchell: Not just categorizing, but also move it to the right place, make PR’s for that
-
@roberth: Problem of interlinking, want to go both directions.
- Suggestion: Tutorials and guides should be in the Nixpkgs source while working on them at least.
- E.g. load Nixpkgs sources into the nix.dev build to publish them. Invest into tooling to make this work smooth.
- @fricklerhandwerk: Partially moving things around in Nixpkgs is good, fairly low context required.
-
@roberth: Problem of interlinking, want to go both directions.
-
@fricklerhandwerk: Let contributors help providing overview, categorization, maybe picking apart the Wiki as well, let @roberth do infrastructure
-
@zmitchell: Nixpkgs content categories are mixed, can’t easily be separated.
-
@roberth: Everything inside Nixpkgs would be better, more integration
- @henrik-ch: Merge nix.dev into the Nixpkgs repo?
-
@fricklerhandwerk: Doesn’t matter where the information lives, have to compile it into an overview in the end.
- Not opposed to the monorepo idea.
- @fricklerhandwerk: Currently there’s too much arbitrary interleaving, people shouldn’t have to read the reference material back-to-back.
-
@roberth: Everything inside Nixpkgs would be better, more integration
-
@infinisil: nix.dev just as the infrastructure repo pulling content from various official projects, Nix, Nixpkgs, NixOS. NixOps, Hydra, too?
-
@henrik-ch: You can send documentation survey interests my way
-
@fricklerhandwerk: Triaging PRs and doing reviews as far as possilbe could be another thing for volunteers.
-
@proofconstruction: From my outside perspective, there’s some ideas, e.g. want tutorials and guides to move to nix.dev
- Is there any document describing this intention? How do I know what’s tutorial, what’s guide, etc.?
- @fricklerhandwerk: Currnet mission statement which links to Diataxis and documentation
- What volunteers can do depends on their background. Some might not even be developers, maybe not familiar with Git/GitHub
- Brute forcing requires a huge amount of effort
- @fricklerhandwerk: This doesn’t require a lot of expertise to work on it
- Brute forcing requires a huge amount of effort
- Is there any document describing this intention? How do I know what’s tutorial, what’s guide, etc.?
-
@proofconstruction: From my outside perspective, there’s some ideas, e.g. want tutorials and guides to move to nix.dev
-
@fricklerhandwerk will assign tasks via GitHub issues to better keep track of them
doc/hacking: note a cause of ./configure failing under zsh by lf- · Pull Request #8455 · NixOS/nix · GitHub
- No conclusion reached last time
- That’s how NixOS Wiki and nix.dev was born, writing down various small hacks all over the place
- We need these somewhere
- @infinisil: Create more links from guides to issues you might run into on a different page
-
@zmitchell: Working on sphinx tags and redirects. Tagging more fine-grained requires splitting up into smaller pages, doesn’t sound good, but is an option
- Might want something other than sphinx at some point
- Alternatives: Roam research?, logseq?
-
@fricklerhandwerk: Not bad to have a hacky, low-tech solution as long as it works
- Alternative: Doing everything in Nix, quite suitable for templating and such
- @infinisil: Home - Styx Static Site Generator
-
@infinisil: Infrastructure seems important, keep getting stuck on it
-
@fricklerhandwerk: As long as that’s the case we can just do content shoveling to move forward at all
- Put things on one pile instead of having multiple, would solve part of the scatteredness problem
- Then go continuosly about sorting the piles, Diataxis is one such coarse structure
-
@fricklerhandwerk: As long as that’s the case we can just do content shoveling to move forward at all