| 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: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 monopage. | 10:26:25 |
| @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 with a single static website. | 10:27:01 |
| @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. | 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:scs.ems.host | 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:scs.ems.host | 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 |
| 15 Oct 2024 |
|  detroyejr joined the room. | 02:55:49 |
|  dish [Fox/It/She] joined the room. | 03:21:33 |
|  @marshmallow:althaea.zone joined the room. | 06:17:43 |
|  lassulus joined the room. | 07:45:33 |
|  unaboomer_ joined the room. | 08:11:17 |
| 17 Oct 2024 |
|  tdillenburg changed their display name from tiagod to tdillenburg. | 01:41:41 |
|  Dominic Mills set a profile picture. | 17:15:08 |
 ronef | Hey, every NixCon I do a collaborative "State of the Union" where folks from various efforts/teams come share a slide for two minutes and a call to action. Thought to check if someone from the docs team might be interested and is coming to NixCon! | 20:55:27 |
| 19 Oct 2024 |
|  jwillikers joined the room. | 12:09:32 |
|  mwoodpatrickmx joined the room. | 17:01:01 |
| 22 Oct 2024 |
|  willbush changed their profile picture. | 09:29:11 |
|  @federicodschonborn:matrix.org joined the room. | 12:16:59 |
|  Oleg Kaminskiy joined the room. | 23:46:10 |
