| 8 Oct 2024 |
 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 |
 Deleted -Johannes Kirschbauer- reach me via @hsjobeki:matrix.org instead | 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 |
