Attendees: @lucperkins @fricklerhandwerk @yuki_is_bored @infinisil @edolstra
Notes: @lucperkins, with help from @infinisil and others (drawn from HedgeDoc)
Agenda: Nix documentation · GitHub
-
Announcing new acting team lead. Valentin Gagarin @fricklerhandwerk from Tweag is handing the reins over to Luc Perkins @lucperkins from Determinate Systems.
-
Priorities for upcoming quarter
- Theme: unblocking, pt. 2
- Contributor guides
- nixos.org
- Easy contribution: Markdown, standard static site generator, designed for mere mortals
- nix.dev
- Unclear ownership
- Making it an official source (removing opinionated bits, like avoiding
with) - Definitive Nix community source
- “Cookbook”-y; realizing user stories.
- @yuki_is_bored: Sometimes reads more like a tutorial than a cookbook.
- Separate user guides and tutorials
- @fricklerhandwerk: eventually we should have different “books”, one for each category
- @infinisil: Leave in opinionated bits but mark them as opinionated?
- @fricklerhandwerk: @edolstra, how has the community previously handled similar controversial questions?
- @edolstra: we don’t have an established process that has proven successful
- @fricklerhandwerk: may be food for contributing guides, at the least to set expectations
- possible recommendation to contributors: break down pull requests to changes that are unambiguously improvements
- @lucperkins: the foundation should foster the broader discussion how to deal with substantial changes, this is out of scope for documentation
- @fricklerhandwerk: may be food for contributing guides, at the least to set expectations
- @edolstra: we don’t have an established process that has proven successful
- @lucperkins will set forth an action plan in the upcoming docs team meeting. Discussion and potential divvying up of tasks to follow.
-
Moving on to docs team agenda
- Add spellcheck by ners · Pull Request #374 · NixOS/nix.dev · GitHub
- @lucperkins: looks like everyone agrees it’s a good change. should we merge it and see how it goes, rip out if it’s in the way?
- @fricklerhandwerk: missing instructions how to use it, would wait for @ners to provide more docs
- @infinisil: doesn’t seem to work when running
nix build, surely needs more instructions- running
spellcheckadds misspelled words to the exception list, which doesn’t seem like expected behavior
- running
- @infinisil: doesn’t seem to work when running
- should it be part of the normal contribution workflow?
- @infinisil: yes, the problem is only that the implementation is fairly opaque
- think it should be a separate script
- @fricklerhandwerk: this is secondary for this PR, can still change this later
- @ners, please provide instructions how to use it and how you envision it being used in CI.
- @fricklerhandwerk: missing instructions how to use it, would wait for @ners to provide more docs
- @lucperkins: looks like everyone agrees it’s a good change. should we merge it and see how it goes, rip out if it’s in the way?
- Add information on contributing documentation in "How to Contribute" · Issue #350 · NixOS/nix.dev · GitHub
- Add spellcheck by ners · Pull Request #374 · NixOS/nix.dev · GitHub
Note from new team lead, @lucperkins: I’m still getting the hang of this, so bear with me for a little bit here
. Many thanks to @fricklerhandwerk for his past and continued service and for a smooth transition. Looking forward to confronting the many challenges in this domain!