2023-05-08 Documentation team meeting notes #46

fricklerhandwerk · May 9, 2023, 9:05am

Video conference
GitHub project board
Team details
Past meeting notes
Attendees: @fricklerhandwerk @infinisil @zmitchell @StefanSchroeder
Notes by: @infinisil

Agenda

review PRs to improve nix.dev site structure

Notes

Reviewing Create an issue template for site improvements by zmitchell · Pull Request #534 · NixOS/nix.dev · GitHub
@zmitchell: From recent Clojure conference: https://www.youtube.com/watch?v=fTtnx1AAJ-c
Reviewing Create an issue template for tracking issues by zmitchell · Pull Request #533 · NixOS/nix.dev · GitHub
- Problem: Need access to edit other people’s tracking issues
- There’s Requesting documentation team membership · Issue #221639 · NixOS/nixpkgs · GitHub, but only for team membership
- @infinisil: Shouldn’t the docs team have write permissions to nix.dev by default?
  - @fricklerhandwerk: Define a permission scheme for maintainers · Issue #33 · NixOS/foundation · GitHub, but no progress so far
- Opened https://github.com/NixOS/nix.dev/issues/539
Reviewing Set structure of Recipes section by zmitchell · Pull Request #537 · NixOS/nix.dev · GitHub
- @zmitchell: Didn’t add tags since we don’t have a setup for that yet
  - Should maybe do infrastructure for tags first
  - There’s Sphinx Tabs — sphinx-tabs documentation but not sure if that’s what we want
    - @fricklerhandwerk: Looks good, also allows linking from specific manual sections to specific tags
- @zmitchell: Not sure if it makes sense to split into individual files at this stage
  - @zmitchell: If guides don’t have a substantial amount of content might not work that well to have a separate page for it
  - @fricklerhandwerk: Those one-liners shouldn’t be guides at all
  - @zmitchell: What to do with them now though?
  - @fricklerhandwerk: Questions: Is it a guide? Is this where it should go? Tutorials and references shouldn’t be in guides.
  - @infinisil: Only move things to a new structure if we know it should be there
@zmitchell: @pennae said that removing ePub rendering could entirely remove docbook from Nixpkgs
- @fricklerhandwerk: Could break it to see if anybody is using it
- @StefanSchroeder: Is there a standard way to deprecate things?
- @infinisil: Should deprecate it, can do eval warning
- @fricklerhandwerk: Will always be rendered, needs warning in the content
@zmitchell: Need some help with Automatically update _redirects file · Issue #522 · NixOS/nix.dev · GitHub
- @infinisil: Can ping me
Reviewing Set the structure of the tutorials section by zmitchell · Pull Request #538 · NixOS/nix.dev · GitHub
- What to do with recommended reading and influences, should probably be moved somewhere
  - This is reference documentation, a “what” type of information
- Move dev env to the first steps
- Remove NixOS nesting
- Discussion on wording the tutorial overview
  - @StefanSchroeder: Should have a brief overview over what people can expect from it, should be a really brief summary
  - @fricklerhandwerk: Summary sentence should probably be in the frontmatter so it can be extracted into the index
    - @StefanSchroeder will investigate how to set it up
    - @fricklerhandwerk: if it turns out to be too involved, maintain it manually for now. contents are more important than scalability at the moment
  - @StefanSchroeder: Should also have prerequisites for each tutorial
    - @fricklerhandwerk: already encoded in the tutorial writing guide but not applied everywhere yet
      - help welcome! we need more people doing the word shoveling

Next time we will discuss applications for the documentation project. This meeting will be only for documentation team members, and closed to the public.

zmitchell · May 11, 2023, 3:21pm

Small correction, the Sphinx extension we’re looking at here is sphinx-tags, not sphinx-tabs.