2023-06-01 Documentation team meeting notes #51

fricklerhandwerk · June 1, 2023, 9:07pm

Video conference
GitHub project board
Team details
Past meeting notes
Attendees: @infinisil @fricklerhandwerk @henrik-ch @maj @roberth @zmitchell @khaled @ehmry
Notes by: @infinisil

Agenda

updates and blockers
brainstorming on fostering docs maintenance

Notes

What’s the status, anybody blocked, etc.?
- @maj observing Learning Journey meetings. Have some questions, probably better offline
- @maj: Looking at usability surveys first. First goal is to organize user types, looking for which use cases draw which users, seeing some patterns. Will share a doc link in the Matrix.
  - @fricklerhandwerk: Maybe maintainers directory?
    - @zmitchell: It’s just intermediate notes, nothing persistent yet
    - @maj: We should think about which parts should be persisted further vs. less-important notes, but this doesn’t need to be discussed now
- @fricklerhandwerk: Worked on Nix documentation, merged the “What is Flakes” PR to nix.dev.
- @roberth: I don’t have any tasks yet, no questions

Going through open issues and PR’s, also good for @maj to see, and we have a pile of them:

Find maintainer for NixOS manual · Issue #217858 · NixOS/nixpkgs · GitHub is important
- Maybe it should be broken down, making it easier, some people were interested in picking up parts
Remove Package Management chapter · Issue #7769 · NixOS/nix · GitHub
- Can be done by anybody, small and incremental
@fricklerhandwerk: I have a bunch of Flakes-related PR’s open
@fricklerhandwerk: Some PR’s for @roberth to review/approve
@fricklerhandwerk: @zmitchell: Delegate fixing redirects to @roberth?
- @zmitchell: Pairing would be good to get into the Nixpkgs contributing
- Relevant for Set the structure of the tutorials section by zmitchell · Pull Request #538 · NixOS/nix.dev · GitHub, links are getting broken when moving things
- Related:
@fricklerhandwerk: Generally use opportunity for knowledge sharing when @roberth available, write down documentation if possible
Find maintainer for NixOS manual · Issue #217858 · NixOS/nixpkgs · GitHub
- How to make this more approachable even without assuming funding?
  - @infinisil: Breaking it down is necessary, nobody would take on the entire Nixpkgs manual
  - @fricklerhandwerk: Could contact language/framework teams to take on code ownership
    - @infinisil: How does it look like in practice? Can we write this down for the potential owners?
    - @fricklerhandwerk: Written down somewhat in https://nix.dev/contributing/documentation#manuals, but we should maybe be more concrete
  - @fricklerhandwerk: Looking at https://github.com/NixOS/nixpkgs/blob/387b4612bf7a323ab1176b64699f7ada1cff2fba/maintainers/team-list.nix
    - @roberth: Could you go through these teams, contact if active, and map them to the manual sections?
      - The team should be code owners, but they might not have a GitHub Team
    - @infinisil: Could have better infrastructure to automatically create GitHub Teams or update team-list.nix
  - @roberth: Sometimes people don’t want to get spam from rebase mistakes
    - @infinisil: Third-party GitHub Actions could be used instead of code owners for more flexibility and fixing such problems
  - @fricklerhandwerk: @roberth could gently ask people to take on some work of cleaning up the manual
    - @roberth: Not very comfortable asking peoplo to migrate stuff, would also need review, improvements
  - @infinisil: Could we have a process for e.g. deprecating manual sections if nobody maintains them
  - @fricklerhandwerk: Got flak for (re)moving stuff (ever so carefully)
    - @infinisil: Could link to a markdown document in an old Nixpkgs commit
  - @infinisil: I guess it doesn’t work that well, because users that need the docs wouldn’t take on ownership, and the ones who would maintain it don’t read the docs
    - @fricklerhandwerk: A perennial problem…
What’s the state of the NixOS manual?
- @roberth: Lots of services chapters, integrated with the module system
  - Very minimal module system docs are in here, probably shouldn’t even be in the NixOS manual, since it’s not specific to NixOS
- @infinisil: Module system documentation refactor by spacekookie · Pull Request #526 · NixOS/nix.dev · GitHub was started
@maj: Who has access to these manuals? Who would be in charge of getting rid of this stuff? Who has the authority?
- @fricklerhandwerk: The doc team is currently the closest to that
@maj: How to figure out how teams are active?
- @fricklerhandwerk: Could query git log and match them to the members in lib.maintainers and teams, see Sign in to GitHub · GitHub and https://github.com/NixOS/nixpkgs/blob/387b4612bf7a323ab1176b64699f7ada1cff2fba/maintainers/team-list.nix, not necessarily in sync
- @roberth: I can communicate with them, asking them to keep the teams listings up-to-date themselves.
  - Will ask them to take code ownership, but moving/migrating later
@maj: Is the goal to keep the older material around?
- @fricklerhandwerk: Everything that’s not a reference should go to nix.dev. We aren’t sure about how-to guides, discussed that in the past without conclusion so far.
- @zmitchell: It’s not entirely clear how to put things into the tutorials section. Can’t just have a flat listing of dozens of tutorials, should group them. But then the question is how to categorize them.
- @maj: Seems to be blocked on the teams being specified and taking ownership
- @fricklerhandwerk: Could do it myself, but I’m getting stuck at where to put it as well
  - One idea was to create a database-like structure, or assign tags. Alternatively @infinisil’s suggestion to write tutorials next to the code in e.g. Nixpkgs, then import and render those on nix.dev. Many options, but haven’t decided on anything.
@maj: Has there been another place where information has been stored?
- @fricklerhandwerk: The NixOS/Nixpkgs/Nix manuals even nowadays contains most official documentation, a Diátaxis mix, e.g. see Nixpkgs 24.05 manual | Nix & NixOS
  - @zmitchell: https://nixos.wiki/ also exists, but not well maintained or curated, not our domain, not official
@roberth: Agreeing with @infinisil’s idea to have documentation right next to the code. It’s much harder to maintain documentation in a separate repo. Tooling for this would be great.
- @fricklerhandwerk: Please spend some time to write a proposal for how such tooling could work.
  - Related example: https://github.com/NixOS/nixpkgs/tree/master/lib/path
  - Structure could be: each how-to is in a file, have frontmatter tags, etc.
- @roberth: Should be possible to find a good place for all docs
  - @zmitchell: Clarification?
  - @roberth: Three projects to distinguish:
    - Import tutorials/guides from Nixpkgs to nix.dev [semi?-]automatically, new and curated documentation
    - Split up doc directory in Nixpkgs, move files to where they belong functionally
    - Change the layout of the manual, single-page is terrible
      - @fricklerhandwerk: @pennae are working on this at their own pace
@fricklerhandwerk: Did @infinisil consider expanding Nix Hour to have guests?
- @infinisil: Don’t want to spend a lot of time on that, could look around passively