- Meeting info
- Past meeting notes
- Documentation office hours in the NixOS Calendar
- Attendees: @trespaul @hsjobeki @paotsaq @friedow
- Notes by: @friedow
vision doc: nix.dev/maintainers/vision.md at master · NixOS/nix.dev · GitHub
Summary
First meeting on the new structured agenda. Went through recent PRs (a good batch landed, including the doc team becoming codeowner of /doc in nixpkgs), then the discussion half. Main threads: giving Vale a try in nixpkgs, what reference documentation actually is, and breaking up the oversized files. @trespaul was invited to become an official team member.
Action items
Done
- nixpkgs#569842 / nixpkgs#572481: move
lib.typesto the nixpkgs manual. Cleanup still remains. The docs were copied verbatim and weren’t in the best shape. - nixpkgs#570128: add required
ids to every documentation node. Needed to derive stable URIs. Open question: what happens if you merge two files? Add tooling later to keep URLs stable. - nixpkgs#566013: local improvement of the NixOS installation guide (disk formatting section).
- nixpkgs#563270: documentation team is now codeowner of
/docin nixpkgs
. We need to exclude the doc team from codeowners of the release notes, since most PRs touch that. - nixpkgs#567393: styleguide: Clarify to use blockquoted multiline examples.
In progress
- nixpkgs#572065: refactor
doc/README.md(@hsjobeki reviewed). - nixpkgs#506597: document
pkgs.callPackageand friends (@hsjobeki reviewed). - nixpkgs#573331: update the license metadata section (@hsjobeki reviewed).
We still have outstanding review requests. If you want to help, see the full list. We’ll put this out there for others to help review documentation PRs.
PRs to look at
- nix.dev#1289 (@hsjobeki): probably could be broken into two: nix.dev#1297 is the basic plumbing split out of it.
- nixpkgs#565872 (@hsjobeki): needs a replacement for headings in nrd; needs more work and thought from @hsjobeki.
Discussion
Vale (@trespaul)
Can we use Vale more, across all the docs, and add it to nixpkgs? Any suggestions for particular rules? (Vale is an LSP and prose linter.)
- @trespaul has already set up a bunch of Vale rules for nixpkgs. Focus on nixpkgs for now, added as a Nix package for documentation support.
- @hsjobeki: this could be annoying for contributions.
- @friedow: I’d rather not have it running in CI, It would block contributions.
- @trespaul: Vale has severity levels, so we can control which rules fail CI. Could also be a bot.
- @alex: encourage people to run it locally to cut down on prose nitpicks.
- Consensus: let’s give it a gentle try in nixpkgs. If it gets annoying make it optional.
Breaking up long files (@hsjobeki)
We need to break long files like stdenv.chapter.md down into smaller pages.
What is reference documentation? (@paotsaq)
- Reference documentation is closely tied to the source code.
- @paotsaq: why not just link to the code? Most functions have doc-comments, which are their reference documentation. But
stdenvhas no source that can carry doc-comments. It’s one big bash file. Packaging a Go package is a good example of a guide. - @friedow: we have a bunch of READMEs explaining how to write documentation scattered across nix.dev and nixpkgs. There should be a single unified endpoint.
- We’re not using Diátaxis fully. Right now we only have guides and reference.
Team term length (@paotsaq)
How long is the term for the documentation team? There are no terms, it’s just the people who stick around working on documentation.
Other topics raised
- Release notes, marketing team, Nix team (@trespaul).
- Page descriptions (@trespaul).
- Should we do ADRs to record the reasons behind the framework and other decisions?
- how-nixos-works.md. looks like an explanation?
Announcements
- Invited @trespaul to become an official member of the documentation team
