| 14 Dec 2023 |
 infinisil | Totally in favor of splitting it up more btw | 22:02:10 |
 @jade_:matrix.org | maybe we could generate a site out of the nixpkgs source tree to make that nicer? I agree it's nice to have it in grep scope or nearby the code. looks like rustc people put it separately: https://github.com/rust-lang/rustc-dev-guide
I'm kind of either way on this: having a site generated out of the nixpkgs source could potentially make it non-obvious that the thing is also available in nicer form on the web, and it might discourage contributions due to nixpkgs being huge and the various infelicities of github workflows on large repos. But this is not a strong opinion. | 22:05:35 |
| 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 |
