 | Nix Documentation | 420 Members |
| Discussion about documentation improvements around the Nix ecosystem | 87 Servers |
| Nix Documentation | 420 Members |
| Discussion about documentation improvements around the Nix ecosystem | 87 Servers |
| Sender | Message | Time |
|---|---|---|
| 8 Mar 2024 | ||
 infinisil | Ping danielsidhion Johannes Kirschbauer @hsjobeki ^ | 02:41:52 |
| infinisil | Haven't seen it often, but I guess there's no problem with it if it makes sense | 02:43:11 |
 pennae | like, nrd exists for the express purpose of creating manuals at least as useful as docbook was, with xrefs from modules to options etc, and not create totally garbage manpage output like current nix does. the syntax extension are icing | 02:43:13 |
| pennae | we've recently been told that epub support is something at least a few still want, the infra behind html:into-file was with the express purpose of easily allowing any level of detail of splitting so you can make epub happen very easily. (it's not wired up for that right now, but it's like five lines of patch to do) | 02:44:41 |
 @johannes.kirschbauer:scs.ems.host | I understand the frustration you're experiencing, especially considering the significant effort you've invested into the project. However, Danielsidhion and I are currently exploring alternative options because we're trying to providing the best possible experience for our users. This sometimes entails re-thinking our current approach. Adopting an off-the-shelf rendering framework that offers customization options could significantly enhance user-friendliness while reducing complexity and maintenance work. Daniel has a list of needed features like page search, intuitive navigation, handling cross references, md plugins, live editing etc, ultimately improving the overall user experience. I think we might need an RFC if we really want to migrate anyways. This would also allow potential epub users to show up. | 07:52:41 |
| @johannes.kirschbauer:scs.ems.host | * I understand the frustration you're experiencing, especially considering the significant effort you've invested into nrd. However, Danielsidhion and I are currently exploring alternative options because we're trying to providing the best possible experience for our users. This sometimes entails re-thinking our current approach. Adopting an off-the-shelf rendering framework that offers customization options could significantly enhance user-friendliness while reducing complexity and maintenance work. Daniel has a list of needed features like page search, intuitive navigation, handling cross references, md plugins, live editing etc, ultimately improving the overall user experience. I think we might need an RFC if we really want to migrate anyways. This would also allow potential epub users to show up. | 07:53:42 |
| @johannes.kirschbauer:scs.ems.host | * I understand the frustration you're experiencing, especially considering the significant effort you've invested into nrd. However, Danielsidhion and I are currently exploring alternative options because we're trying to providing the best possible experience for our users. This sometimes entails re-thinking our current approach. Adopting an off-the-shelf rendering framework that offers customization options could significantly enhance user-friendliness while reducing complexity and maintenance work. Daniel has a list of needed features like page search, intuitive navigation, handling cross references, md plugins, live editing etc, ultimately improving the overall user experience. I think we might need an RFC if we really want to migrate anyways. This would also allow potential epub users to show up. | 07:54:32 |
| pennae | also don't forget that manpages exist. | 07:55:24 |
| pennae | nix regressed horrifically on its manpages, if you do the same you will do so much more damage than live editing or flashier navigation can give you | 07:56:23 |
| pennae | also consider that nixos-search exists and would do rather better with richer xref medatadata rather than stuff that mostly works in html-only-and-maybe-pdf formats? | 07:57:51 |
| pennae | the reason we didn't push for using eg pandoc to generate the docs is that pandoc (and all other frameworks we've looked at then) fails at least one of those tests, and we've already regressed on things to make even that much happen | 07:59:08 |
 @jade_:matrix.org | It seems borderline absurd to assume that there exists an off the shelf solution that actually has proper interactions with nix and consideration of anything that is not a web browser. Have you considered taking the nrd output and using it in your pipeline instead of trying to reinvent it, so we actually own the markup parser and such? | 07:59:21 |
| pennae | or, as nrd was intended, change nrd to match the needs | 07:59:47 |
| pennae | (we also find it somewhat backhanded to come up with live editing again when that was already hacked into place and not even possible before the md workflow really took off) | 08:07:44 |
| pennae | like, the root problem with our docs isn't tooling support. switching out tooling again will only bind resources that could've been used for something that actually improves that status quo? | 08:08:54 |
| infinisil | In reply to @jade_:matrix.orgAfaik there's nothing Nix-specific about nixos-render-docs at least | 09:45:49 |
| infinisil | In reply to @pennae:matrix.eno.spaceI'd say it's a problem that we use different tooling for different projects. I guess it would make sense to try and see if nixos-render-docs could be used throughout though (such as for Nix and nix.dev). | 09:48:07 |
| pennae | not nix-specific, but nixpkgs/nixos-specific very much so. like manpage export, integration with the option system, crossreferencing, even performance optimizations needed to generate such huge documents as the nixos manual | 09:48:23 |
| pennae | In reply to @infinisil:matrix.orgwe did have that aspiration before we burned out on it all | 09:48:54 |
| infinisil | In reply to @pennae:matrix.eno.spaceIntegration with the option system sounds very interesting, can you link to that? | 09:49:15 |
| infinisil | Oh I guess options.py | 09:49:23 |
| pennae | In reply to @infinisil:matrix.orgcorrect | 09:50:04 |
| infinisil | https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py | 09:50:19 |
| infinisil | Oh so it renders it a bit differently on different targets | 09:50:31 |
| pennae | of course, that's why the manpage isn't terrible | 09:50:57 |
| @johannes.kirschbauer:scs.ems.host | But Is this website really what we'd like to give something to our users? many off-the shelf rendering frameworks are really awesome (compare to our website), and they dont require us to maintain our own markdown parser and instead have more freedom because their community maintains the framework, while we can focus on writing documentation (and maybe add some plugins) | 10:08:02 |
| @johannes.kirschbauer:scs.ems.host | * But Is this website really what we'd like to give to our users? many off-the shelf rendering frameworks are really awesome (compare to our website), and they dont require us to maintain our own markdown parser and instead have more freedom because their community maintains the framework, while we can focus on writing documentation (and maybe add some plugins) | 10:08:26 |
| pennae | have you considered: it took multiple years to do one migration, it has regressed, and it was only possible because we didn't use off-the-shelf components or we would've regressed even more. | 10:09:04 |
| pennae | do you really want to bind up another few years worth of work after the first migration hasn't even been shipping for six months | 10:09:27 |
| pennae | it's so far from "just drop in another framework", we're not sure you even understand what you're setting yourselves up for. | 10:10:18 |