- Meeting info
- Past meeting notes
- Documentation office hours in the NixOS Calendar
- Attendees: @friedow @hsjobeki @trespaul @sheeeng
- Notes by: automated transcription (experiment)
vision doc: nix.dev/maintainers/vision.md at master · NixOS/nix.dev · GitHub
Summary
Mostly about how to restructure the manual for the new goal-ordered site: how to split chapters into guide vs reference without scattering related text, and how to sort package docs. Round-robin review is now on. We experimented with a self-hosted STT-model to take speaker notes in this meeting. Most of us are busy with day-work right now, so a chunk of the discussion was about scoping docs.nixos.org work down into pieces people can actually pick up.
Action items from last time
These all merged / progressed:
- nixpkgs#572065: refactor
doc/README.md. merged. The contributor removed the “write guides / write reference” lines, but those were deliberate: they follow Diátaxis and showed the planned top-level navigation. - nix.dev#1297 initialized nixpkgs markdown rendering into docs.nixos.org (only merged, not deployed yet)
See: Project board (important stuff)
Whole backlog of review requests: full list if you want to help.
Discussion
Tutorial vs. guide
@trespaul: Getting Started is really a tutorial, since the docs pick the goal for the user, whereas a guide solves a goal the user brings. General agreement.
@hsjobeki wants readers to only ever see the term “guides”, because visitors and contributors keep confusing the two. @trespaul thought Getting Started / Guides / Reference works.
Splitting the manual
The current manual is a single page ordered by topic; the new site will be ordered by goal. The problem: splitting a chapter like stdenv or cross-compilation into a guide file and a reference file pulls related text far apart on the single page.
- @trespaul: the whole split fits in one PR if we build a mapping list first.
- @hsjobeki: prefers to go slowly.
- Both agreed on cross-links in both directions. @hsjobeki proposed topic tags that cross-link pages automatically.
“Move Packages section up one level” (nixpkgs#579762)
This brought up a broader discussion how to lay out the structure of the nixpkgs manual:
@trespaul hadn’t approved this PR since the team hadn’t discussed it yet. Where things land:
Ideas:
- Package-specific guides stay under Guides, same level as languages and frameworks.
- Generic helpers (
mkDerivation, hooks) get a section separate from package-specific ones (fetchFirefoxAddon). - Package-specific content that’s just a list of functions goes to Reference.
- Maintainer info (e.g. for the Linux kernel) goes to contributing docs or a README next to the package.
- Explanation pages like “how channels work” get rewritten as how-to guides.
- Each piece of content lives in one place; other pages link to it.
- @friedow wants package docs to sit next to the package once docs.nixos.org lists every package.
Likely to be approved once the guide split above is sorted.
Bug fixed along the way: Inkscape link
It points at a search.nixos.org query for CUDA packages, which is wrong. Plan: for now: link packages to search.nixos.org. Later, search for those URLs and swap them for internal links once each package has its own page.
Documentation project board
@hsjobeki cut it from ~900 items down to ~100. The labels pull in every PR that touches doc/release-notes included, so most items there are just one-line release-note changes. The owners file handles this better because it can exclude directories. We need the same filter for the board, but it can only work with labels.
Review load
@friedow asked whether reviewing docs PRs is worth the team’s currently limited time. He’d rather push docs.nixos.org forward. @trespaul only checks the language, which costs him little. @hsjobeki doing the same, and the long-term aim is to teach contributors to write good docs, so the team itself becomes mostly redundant.
How to help / scoping
@sheeeng asked how to help, suggestions were:
- small doc fixes on a topic he cares about
- splitting or merging files to improve structure
More generally, with everyone busy, the aim is to scope docs.nixos.org work into smaller pieces.
Rendering
@trespaul fixed the heading scale but hasn’t opened a PR yet.
@hsjobeki is turning on the heading-attributes renderer. More rendering PRs coming.
@friedow wanted to take over navigation sidebar styling
Decisions
- Round-robin review turned on in the GitHub team settings. One reviewer per PR, @friedow excluded so he can focus on docs.nixos.org.
- If needed: Link packages to search.nixos.org (without a channel in query params) for now; We’ll grep-replace with internal links later once each package has a page.
- The “Move Packages” PR is approved and merged. Follow ups to improve structure will be discussed in the next meeting.
Actions
- @trespaul: open a PR for the heading scale and headings.
- @friedow: improve the sidebar without over-engineering it. Sidebar state stable across page navigation using the Alpine store / local-storage.
- everyone: unsubscribe us from release-note-only PRs, they are noise right now.
- everyone: In the next meeting we’ll be drafting the manual structure.
- @sheeeng: pick a topic and make small documentation improvements.