 | Nix Documentation | 419 Members |
| Discussion about documentation improvements around the Nix ecosystem | 84 Servers |
| Nix Documentation | 419 Members |
| Discussion about documentation improvements around the Nix ecosystem | 84 Servers |
| Sender | Message | Time |
|---|---|---|
| 8 Oct 2024 | ||
 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.orgWiki != 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:
| 15:45:39 |
 tea | In reply to @brunbjerg:matrix.orgUsually 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.orgOr 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 |