| 24 Sep 2024 |
 getpsyched | In reply to@phanirithvij:matrix.org
has anything been done for rendering docs in multiple pages since this discussion? Hi, I've been working on the render docs as part of splitting the manuals into multiple pages. Currently the work is on getting a robust redirect system set up. As @Johannes Kirschbauer @hsjobeki outlined, I'm working on the same things and have pieced out the details in a roadmap which I'll convert into a formal documentation page after we hit the redirects milestone.
Feel free to track the progress through this diff:
https://github.com/NixOS/nixpkgs/compare/nixos-24.05...GetPsyched:nixpkgs:render-docs
The base branch is set to 24.05 as we're aiming to backport these changes there and jump to master/24.11 and run our script again to retro-actively catch breakages. | 11:42:18 |
|  @terru:raccoon.college left the room. | 12:34:49 |
|  mei 🌒& changed their profile picture. | 23:25:17 |
| 26 Sep 2024 |
|  Fabián Heredia set a profile picture. | 01:15:49 |
| 27 Sep 2024 |
|  @zardian:matrix.org left the room. | 14:03:08 |
|  loudgolem changed their display name from phanirithvij to loudgolem. | 14:38:01 |
| loudgolem changed their profile picture. | 14:38:28 |
|  elikoga (@38c3 📞488{0,1}) 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 (@38c3 📞488{0,1}) | 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 |
