| 14 Dec 2023 |
 @jade_:matrix.org | matrix is not a work item tracker | 21:51:28 |
| @jade_:matrix.org | some of this stuff is legitimately just a matter of doing the work | 21:51:44 |
 raitobezarius | agreed | 21:52:17 |
| raitobezarius | it's good for realtime and is lossy because of missing indexation | 21:52:32 |
| @jade_:matrix.org | https://github.com/NixOS/nixos-homepage/issues/1191 filed a bug, i might do it myself in a week | 21:52:50 |
 infinisil | jade_:
CONTRIBUTING.md is a guide level explanation of things, and is already too bloody long. It is the wrong place to provide reference level material about our vision for docs.
| 21:59:35 |
| infinisil | I recently made a big effort to make contributing documentation more coherent: https://github.com/NixOS/nixpkgs/pull/245243 | 21:59:57 |
| @jade_:matrix.org | oh and re why it feels out of place on nix.dev, I am in favour of a just contributors site for which nobody feels shame adding sections or putting potentially less polished content on there, but maybe this is a misread of the values involved | 21:59:59 |
| infinisil | Contributing docs should be accessed from the source code as directly as possible, because this kind of thing keeps changing | 22:00:49 |
| infinisil | Compared to the user documentation, which needs to document stable interfaces | 22:01:11 |
| @jade_:matrix.org | I think my perception of it being very long is also related to GitHub being somewhat troubled with respect to pleasantness of reading long markdown files (even though it even has a table of contents and such!) | 22:01:37 |
| 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 |
