| 14 Dec 2023 |
 infinisil | jade_: Maybe we just need more page splitting, more overviews and more cross-linking in the markdown files | 22:06:51 |
 @jade_:matrix.org | yeah, I think mdbook would be nice for search among other things | 22:07:04 |
| @jade_:matrix.org | like, having a nice sidebar also | 22:07:14 |
| @jade_:matrix.org | because it's harder to do page splitting if you don't have nice search and navigation | 22:07:32 |
| infinisil | I guess contributor docs being rendered (as I described it in https://github.com/NixOS/nixpkgs/issues/244056) is the problem. Rather it's that older versions of the documentation is too easily accessible if it were in the user manuals | 22:08:11 |
| infinisil | * I guess contributor docs being rendered (as I described it in https://github.com/NixOS/nixpkgs/issues/244056) is the problem. Rather it's that older versions of the contributor documentation is too easily accessible if it were in the user manuals | 22:08:20 |
| @jade_:matrix.org | ah yeah, I am definitely not in favour of putting it in the user manual | 22:08:35 |
| infinisil | Though using the GitHub markdown rendering is also kind of nice because it's one less thing to worry about and maintain | 22:09:05 |
| @jade_:matrix.org | it's useful to delineate this because the style of writing for user manuals and contributor-only docs is rather different | 22:09:13 |
| @jade_:matrix.org | i wonder if we could reuse the nix.dev code somehow without causing ourselves too much pain? | 22:09:25 |
| infinisil | I think ideally all .md files in Nixpkgs would be collected somehow and rendered together | 22:10:20 |
| infinisil | (well, user docs are also written in .md, those shouldn't be included obviously) | 22:11:16 |
| infinisil | Oh, but alternatively, what if the render pipelines are separate, but the website puts them into a single document | 22:11:54 |
| infinisil | Such that when you go to nixos.org/manual/nixpkgs, it shows you both stable/unstable versions of the released user documentation, but also the latest contributor documentation from master | 22:12:57 |
| infinisil | This is generally what I think we should have: A single page that collects materials from different repos | 22:13:22 |
| infinisil | And actually we did make a step in that direction with nix.dev: https://nix.dev/reference/nix-manual | 22:13:41 |
| infinisil | I'd be in favor of making nix.dev be the centralised place for docs (but really all of Nix, see https://github.com/nix-rfc-canonical-domain/rfcs/blob/canonical-domain/rfcs/1000-canonical-domain.md) | 22:14:26 |
| @jade_:matrix.org | In reply to @infinisil:matrix.org
Such that when you go to nixos.org/manual/nixpkgs, it shows you both stable/unstable versions of the released user documentation, but also the latest contributor documentation from master maybe i am cynical (i read the sources nearly every time i have a docs query :V), but i am greatly most likely to read the contributing docs if they are a "dev only" site with a simplified contribution process that is quicker vs other docs.
i think i agree that nix is a different situation than rust with respect to the ratio of users to contributors, and this does change the calculus with respect to how much to promote the dev specific stuff
| 22:18:01 |
| @jade_:matrix.org | 
Download image.png | 22:19:05 |
| @jade_:matrix.org | it would be really nice to have a version selector on-page with these: | 22:19:06 |
| @jade_:matrix.org | overall we need more top bar nav in all our stuff :D | 22:19:20 |
| infinisil | Ultimately it boils down to needing more resources | 22:19:58 |
| infinisil | And tbh, I should also do some stuff now, talking in a Matrix channel doesn't accomplish much unfortunately (though synchronising with others is useful) | 22:20:27 |
| @jade_:matrix.org | yeah, for sure. I think that it would be useful to have some meta-tracking of mini projects to do to improve this | 22:20:29 |
| @jade_:matrix.org | so we can start pointing at the work pile and giving it to others | 22:20:45 |
| infinisil | Just need to define "others" 😅 | 22:21:15 |
| infinisil | Nobody really wants to do that kind of work | 22:21:21 |
| @jade_:matrix.org | anyone not in the in-group, I think we can get help from people who haven't met irl at nixcon on this :P | 22:21:47 |
| infinisil | It does take a lot of time and is not very rewarding work, it's really hard to get anybody to do this | 22:22:31 |
| infinisil | I'm the exception because I get paid for this, definitely not the norm | 22:22:58 |
