| 27 Sep 2024 |
|  elikoga set a profile picture. | 16:27:30 |
| 28 Sep 2024 |
|  thezaedus set a profile picture. | 07:21:15 |
| 1 Oct 2024 |
|  -_o joined the room. | 21:00:25 |
| 4 Oct 2024 |
|  @ajcxz0:matrix.org left the room. | 01:00:45 |
| 7 Oct 2024 |
|  Sam Lehman changed their profile picture. | 14:24:50 |
| 8 Oct 2024 |
|  Christian Brunbjerg joined the room. | 08:19:30 |
| Christian Brunbjerg | Hello community,
Is there a kind of roadmap for the documentation?
Or a place that is the most in need of updating?
Kind regards | 08:21:14 |
 Soenke Klinger | There is no simple answer for this. The answer will be different depending who you ask, and what scope you set.
My personal answer would be:
The documentation - especially the handbooks for nix/nixpkgs and the documentation in search.nixos.org for packages/options and installation and usage procedures are good enough for people who like to read and write code to get a sufficiant understanding of nix and the ecosystem.
In my personal view the documentation is lacking for the „non-coder/linux users but also administrators“ und NixOS - and there https://wiki.nixos.org needs some low level documentation and there are some low hanging fruits, what can be done to improve the situation (documentation about desktop programs and their configuration via simple configuration.nix commands. If you just use your desktop for (office) work and have some small scale servers (maybe a VM-Host and some VMs on it), you may not need Flakes, Homemanager, a deep understanding of nix language, the ability to package for nixpkgs, setup Hydra, do remote builds, have a complex configuration system etc.
But these users need more information about typical desktop and server programs, how to configure it (with full and explained examples), maybe to setup the servers (how to setup an hedgedoc instance for myself and make it safe with .htaccess authentification), or „how to install firefox including some common plugins and some privacy configuration“.
The long-term goal would be: Find a way to include these examples and better documentation for options in nixpkgs itself, in a way that it can be autogenerated in manuals and included in the search results from sites like search.nixos.org.
| 10:54:58 |
| Soenke Klinger | Christian Brunbjerg: Do you have a particular interest to contribute, or need some kickstart-help to do this? | 15:21:23 |
| Christian Brunbjerg | Redacted or Malformed Event | 18:10:44 |
| Christian Brunbjerg | 
Download ima_0a8dae8.jpeg | 18:11:57 |
| Christian Brunbjerg | Thank you for the comprehensive reply.
First, there seems to be multiple different sources of nix documentation. (as shown above)
What is this groups stance on these? It seems to me that we should try to establish a single source of truth for the documentation as the first thing? | 18:13:55 |
| elikoga | In reply to @brunbjerg:matrix.org
Thank you for the comprehensive reply.
First, there seems to be multiple different sources of nix documentation. (as shown above)
What is this groups stance on these? It seems to me that we should try to establish a single source of truth for the documentation as the first thing? Wiki != Documentation | 19:42:36 |
| 9 Oct 2024 |
| Christian Brunbjerg | I think I will need some help to get started then.
I have only used nix for creating reproducible devShells across different repos. A friend asked which distro he should use for a server and I thought that it is a shame that I could not recommend NixOS over Ubuntu given the trouble I had myself.
I have mostly written documentation as markdown above function and class definitions and READMEs
When you talk about documentation, do mean the:
- man configuration.nix?
- the info that you can get on individual packages on search.nixos.org?
- The wikis?
| 15:45:39 |
 tea | In reply to @brunbjerg:matrix.org
I think I will need some help to get started then.
I have only used nix for creating reproducible devShells across different repos. A friend asked which distro he should use for a server and I thought that it is a shame that I could not recommend NixOS over Ubuntu given the trouble I had myself.
I have mostly written documentation as markdown above function and class definitions and READMEs
When you talk about documentation, do mean the:
- man configuration.nix?
- the info that you can get on individual packages on search.nixos.org?
- The wikis?
Usually nix.dev is the first place to check, followed by the nixpkgs and nixos manuals, in my opinion | 16:26:02 |
| tea | nix.dev is supposed to be the "single source of truth" | 16:26:47 |
| 10 Oct 2024 |
 fricklerhandwerk | In reply to @noob_tea:matrix.org
nix.dev is supposed to be the "single source of truth" Or at least the entry point for the several sources of truth for the several system components that are developed independently | 10:02:38 |
| fricklerhandwerk | Soenke Klinger: Having led the documentation effort in the past two years, I agree with your assessment. Reference documentation still needs to be more consistent in terms of presentation and level of detail, but things have improved a lot; also thanks to Johannes Kirschbauer @hsjobeki‘s invaluable work on docstrings. | 10:06:25 |
| fricklerhandwerk | The biggest pain point for users at the moment is getting a grasp NixOS module interfaces. Docs quality in the code is very spotty and discoverability is not great. Most importantly we almost completely lack reliable and sufficiently complete examples.
getpsyched is currently working on the infrastructure to improve some of the discoverability aspects, and I have a prototype going for managing and presenting examples, but all of that will take a while. I’m currently preparing a substantial UX effort that should help address the most obvious, which will need a fundraiser to get the resources needed for implementation.
The irritating thing is that in principle most stuff is there, and the system is incredibly powerful — most of the good bits are just surprisingly hard to find. | 10:10:23 |
 Johannes Kirschbauer @hsjobeki | One of the big painpoints also the multipage rendering. getpsyched Working on that. afaik.
Other painpoint is that we have so many entry points, (nixos-, nixpkgs-, nix- manual, nix.dev)
This adds a whole new dimension, but could be solved with a smart navigation system on a monopage. | 10:26:25 |
| Johannes Kirschbauer @hsjobeki | * One of the big painpoints also the multipage rendering. getpsyched Working on that. afaik.
Other painpoint is that we have so many entry points, (nixos-, nixpkgs-, nix- manual, nix.dev)
This adds a whole new dimension, but could be solved with a smart navigation system with a single static website. | 10:27:01 |
| Johannes Kirschbauer @hsjobeki | * One of the big painpoints also the multipage rendering. getpsyched Working on that. afaik.
Other painpoint is that we have so many entry points, (nixos-, nixpkgs-, nix- manual, nix.dev)
This adds a whole new dimension, but could be solved with a smart navigation system on a single static website. | 10:27:11 |
| fricklerhandwerk | In reply to @johannes.kirschbauer:scs.ems.host
One of the big painpoints also the multipage rendering. getpsyched Working on that. afaik.
Other painpoint is that we have so many entry points, (nixos-, nixpkgs-, nix- manual, nix.dev)
This adds a whole new dimension, but could be solved with a smart navigation system on a single static website. Unifying everything in terms of navigation is not even a technical or design problem — in fact we’ll hopefully be able to make some good progress on the design end of November at the ZHF hackathon in Zurich — but it’s actually blocked on unclear ownership (Is the marketing team still fully operational? Last time I tried to reduce the number of sources of truth it got blocked, but we rarely see activity otherwise.) and a lack of people with enough availability to implement decisions once they’re made. | 10:39:37 |
| fricklerhandwerk | In reply to @brunbjerg:matrix.org
Hello community,
Is there a kind of roadmap for the documentation?
Or a place that is the most in need of updating?
Kind regards The most up to date that we have in terms of global vision: https://discourse.nixos.org/t/a-roadmap-for-the-documentation-ecosystem/42328 | 10:41:02 |
| fricklerhandwerk | In reply to @johannes.kirschbauer:scs.ems.host
One of the big painpoints also the multipage rendering. getpsyched Working on that. afaik.
Other painpoint is that we have so many entry points, (nixos-, nixpkgs-, nix- manual, nix.dev)
This adds a whole new dimension, but could be solved with a smart navigation system on a single static website. * Unifying everything in terms of navigation is not even an insurmountable technical or design problem — in fact we’ll hopefully soon be able to make some good progress on the design, end of November at the ZHF hackathon in Zurich — but it’s actually blocked on unclear ownership (Is the marketing team still fully operational? Last time I tried to reduce the number of sources of truth it got blocked, but we rarely see activity otherwise.) and a lack of people with enough availability to implement decisions once they’re made. | 10:41:46 |
| Johannes Kirschbauer @hsjobeki | Maybe it would Help If we could ask for Money. Like CTF, each task gets a reward of lets say 1k-2k or sth. We have the Vision, the milestones. Just Lack of Motivation from enough people. | 10:52:08 |
| Johannes Kirschbauer @hsjobeki | Maybe we can raise a pot of Money for all the Framework and infra refactoring Tasks. | 10:59:59 |
|  p4cmanus3r joined the room. | 13:26:17 |
| fricklerhandwerk | In reply to @johannes.kirschbauer:scs.ems.host
Maybe we can raise a pot of Money for all the Framework and infra refactoring Tasks. Yes, we can put up a funding goal on https://opencollective.com/nixos/projects/nix-documentation
Just need to define concrete, achievable deliverables.
| 14:27:17 |
|  requiem33 joined the room. | 22:40:04 |
