# 2026-10-28 Documentation team meeting notes
**URL:** https://discourse.nixos.org/t/2026-10-28-documentation-team-meeting-notes/80842
**Category:** Documentation
**Created:** [October 29, 2026, 1:23pm UTC](https://discourse.nixos.org/t/2026-10-28-documentation-team-meeting-notes/80842 "2026-10-29T13:23:16Z")
**Posts on this page:** 4
**Page:** 1
### Author:  [@hsjobeki](https://discourse.nixos.org/u/hsjobeki)
#### Post date: [October 29, 2026, 1:23pm UTC](https://discourse.nixos.org/t/2026-10-28-documentation-team-meeting-notes/80842/1 "2026-10-29T13:23:16Z")
- [Meeting info](https://github.com/NixOS/nix.dev/tree/master/maintainers#team-meetings)
- [Past meeting notes](https://discourse.nixos.org/search?q=meeting%20notes%20%23dev%3Adocumentation%20in%3Atitle%20order%3Alatest)
- [Documentation office hours in the NixOS Calendar](https://calendar.google.com/calendar/u/0/embed?src=b9o52fobqjak8oq8lfkhg3t0qg@group.calendar.google.com)
- Attendees: [@friedow](https://discourse.nixos.org/u/friedow) [@hsjobeki](https://discourse.nixos.org/u/hsjobeki) [@trespaul](https://discourse.nixos.org/u/trespaul) [@sheeeng](https://discourse.nixos.org/u/sheeeng)
- Notes by: automated transcription (experiment)
vision doc: [nix.dev/maintainers/vision.md at master · NixOS/nix.dev · GitHub](https://github.com/NixOS/nix.dev/blob/c51f7d3d283fdaae114f555d4a6bfc3805870913/maintainers/vision.md)
## 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](http://docs.nixos.org) work down into pieces people can actually pick up.
## Action items from last time
These all merged / progressed:
- [nixpkgs#572065](https://github.com/NixOS/nixpkgs/pull/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](https://github.com/NixOS/nix.dev/pull/1297) initialized nixpkgs markdown rendering into [docs.nixos.org](http://docs.nixos.org) (only merged, not deployed yet)
See: [Project board](https://github.com/orgs/NixOS/projects/15) (important stuff)
Whole backlog of review requests: [full list](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+draft%3Afalse+team-review-requested%3ANixOS%2Fdocumentation-team+sort%3Aupdated-desc) 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](https://github.com/NixOS/nixpkgs/pull/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](http://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](http://search.nixos.org) query for CUDA packages, which is wrong. Plan: for now: link packages to [search.nixos.org](http://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](http://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](http://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](http://docs.nixos.org).
- If needed: Link packages to [search.nixos.org](http://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.
---
### Author:  [@ahoneybun](https://discourse.nixos.org/u/ahoneybun)
#### Post date: [October 29, 2026, 2:14pm UTC](https://discourse.nixos.org/t/2026-10-28-documentation-team-meeting-notes/80842/2 "2026-10-29T14:14:30Z")
On the subject of labels I don’t see any issues with ‘help wanted’ or ‘paper cut’ such as issues that would be good things to be someone’s first PR. Is that planned and just not at this stage yet?
---
### Author:  [@hsjobeki](https://discourse.nixos.org/u/hsjobeki)
#### Post date: [October 29, 2026, 4:32pm UTC](https://discourse.nixos.org/t/2026-10-28-documentation-team-meeting-notes/80842/3 "2026-10-29T16:32:46Z")
Yes that would be a good improvement i haven’t got around to prioritize and categorize the issues in depth yet. Are you looking for a good first issue on the board, or just curious about it?
If you got some personal thoughts on what issues or topic are more important I’d love to hear it.
---
### Author:  [@ahoneybun](https://discourse.nixos.org/u/ahoneybun)
#### Post date: [October 29, 2026, 4:45pm UTC](https://discourse.nixos.org/t/2026-10-28-documentation-team-meeting-notes/80842/4 "2026-10-29T16:45:29Z")
Yes I haven’t been able to make it to the meetings but I would like to help where I can but also curious about it.
I’ve been trying to get some folks at work behind nix and using it for development and would love to have some nice docs to point them to. Right now things are in a few different places such as [https://nix.dev](https://nix.dev).