2023-10-26 Documentation team meeting notes #89

fricklerhandwerk · October 27, 2023, 3:43am

Agenda/Notes

@asymmetric would like to discuss the following:

(“New definitions (as in defining the terminology):” items)
this should be merged first, so that we get naming right before merging the stuff below
would like to get clarity on verbs, not just names, as this is very important in documentation
- i.e. “define an option” becomes ???
@infinisil: consistency and explaining the concept is more important than the naming
- @roberth: that’s orthogonal
@asymmetric: if there is agreement it could be an easy win
@fricklerhandwerk: may be a bit too much to do it right now, let’s schedule time to discuss
@infinisil should take a closer look at this

who can upload the video to an official channel?
- for example, we have the nixos foundation channel
why not merge it?
- this would allow iteration to be unblocked by Infinisil’s capacity to integrate feedback on the existing PR
There’s an update by @fricklerhandwerk and @proofconstruction in https://github.com/NixOS/nix.dev/pull/730
Relies on Google maps API which is non-trivial to get access to
Too many lines to fix up quickly
Needs some work (TODO’s in the text, some review comments)
The new PR could be merged when done
@asymmetric @fricklerhandwerk and @proofconstruction will do the fixups later today
@infinisil: Look into hosting the presentation somewhere better

@asymmetric: IMO this is not a reference, it should go in nix.dev under concepts
- it is basically an “explanation” under their naming scheme: The difference between reference and explanation - Diátaxis
- @fricklerhandwerk: that’s fine to have in the manual, because it needs some context. in nix.dev we can provide a shallow overview and link to that
@roberth: what we won’t do in the manual but definitely need is teaching skills, such as how to approach a problem with the module system, as it’s a fairly unique thing
let’s have a short overview of the module system on nix.dev
@roberth: Will look into splitting it up so we can merge it in smaller parts

Learning Journey WG now lead by @proofconstruction, does it still make sense to meet and have it?
- Not really been happening anymore, let’s match reality
  - deleted the corresponding GitHub team
  - @fricklerhandwerk will garbage-collect the team directory on nix.dev GitHub
NixOS homepage doc team update Docteam membership update by henrik-ch · Pull Request #1136 · NixOS/nixos-homepage · GitHub
- Updated and merged
- Made it consistent with the GitHub team and the private matrix channel (only used in exceptional cases)