| 8 Mar 2024 |
 danielsidhion | My approach to looking into other frameworks is based on a simpler thought: we currently have 5k lines of custom code to render the manuals into what we see online. As far as I know, there is currently not a lot of flexibility in the tool to produce things in different ways, which means that if we want to change something, we'll need to go change the code. This is a big overhead that makes it hard to add improvements to the manuals. So I decided to look into other frameworks to see how much of our needs they can satisfy out of the box, and how much extra effort would be needed to satisfy the other needs. Because honestly, I actually find borderline absurd to assume that nobody out there has been able to solve some of the same problems we have into a tool that's more popular, has people to maintain it, and has a bigger ecosystem of documentation/plugins/knowledge to source from | 10:11:24 |
 @pennae:matrix.eno.space | most people out there are not multiple distros in a trench coat | 10:12:29 |
| danielsidhion | But our documentation doesn't have to follow suit | 10:13:54 |
| @pennae:matrix.eno.space | we can only stress again: make sure you're familiar with the problem domain before trying to Be Like The Others. | 10:14:32 |
| @pennae:matrix.eno.space | apart from that, we're not picky about nrd being replaced if there's something better. it's on you to find that thing though, and if you do, awesome! just consider the amount of effort it all takes to migrate again, the regression it will come with, and whether perhaps the tooling we have isn't fine enough if you just take a day to understand how it works | 10:15:45 |
| @pennae:matrix.eno.space | ¯\_(ツ)_/¯ your decision. | 10:16:14 |
 @johannes.kirschbauer:scs.ems.host | Maybe we could have a chat about this guys.
I feel like both parties have valid points and need to be taken seriously. | 10:16:27 |
| danielsidhion | I'd appreciate any links or resources you can send me that show things that we'll need to solve in the other docs frameworks as well. I have a list of things already, but idk how complete it is | 10:16:57 |
| @johannes.kirschbauer:scs.ems.host | In reply to @pennae:matrix.eno.space
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 As said, i feel like any potential migration needs to go through an RFC, to make sure all important aspects from the community taken into account | 10:19:08 |
| @pennae:matrix.eno.space | In reply to @danielsidhion:nixos.dev
I'd appreciate any links or resources you can send me that show things that we'll need to solve in the other docs frameworks as well. I have a list of things already, but idk how complete it is there's no full list as such in a single place, sadly. but whatever you'd choose would have to do manpage generation that isn't hot garbage (like the nix manpages), be able to run often and quickly (because docs is part of a nixos system build), support all the syntax extensions we have somehow (or rewrite a bunch of the docs), somehow be able to generate the option man/html pages, there's of course the issue of how to handle nixos module documentation chapter (which are distinct from option docs), the different formats of export for downstream consumers. there's more, those are just the few that immediately come to mind | 10:21:31 |
| danielsidhion | What do you mean by manpage generation? Are you referring to https://github.com/NixOS/nixpkgs/blob/master/doc/manpage-urls.json ? | 10:22:27 |
| danielsidhion | I didn't have performance on the list, but I'll add it as well | 10:23:06 |
 infinisil | danielsidhion: I think man configuration.nix is meant | 10:23:47 |
| infinisil | I don't think anything else is rendered with man pages | 10:24:17 |
| @pennae:matrix.eno.space | In reply to @infinisil:matrix.org
I don't think anything else is rendered with man pages yes, that was explicitly decided against because generating good manpages and html pages from the same source is damn near impossible | 10:24:44 |
| @pennae:matrix.eno.space | that's why the other nixos manpages are written the old-fashioned way | 10:25:05 |
| infinisil | danielsidhion: Can you publish that list somewhere? | 10:27:00 |
| infinisil | I guess just on https://pad.lassul.us/ would work | 10:27:11 |
| danielsidhion | In reply to @infinisil:matrix.org
danielsidhion: Can you publish that list somewhere? Just quickly copy-pasted from another note I'm keeping, some of the things may not be very descriptive https://pad.lassul.us/TqtuSR-GReyIXHGISZ-S1Q?view | 10:30:02 |
| @johannes.kirschbauer:scs.ems.host | We could still let nrd do manpage rendering tbh. thats something nrd does really well. But i'd favor to migrate the web html stuff specifically. However that could work, we'd need to figure out if we really want to do it. | 10:32:47 |
| @pennae:matrix.eno.space | yes. figure out your needs that aren't met first
(and then you'll probably find that most of them are not hard to add to the tooling that's already in place) | 10:34:20 |
 fricklerhandwerk | Johannes Kirschbauer @hsjobeki: so far all you seem to be lamenting is the web skin. But that’s the cheap part. No off-the-shelf framework will do the domain-specific heavy lifting with an order of magnitude less custom code. | 10:51:33 |
| @johannes.kirschbauer:scs.ems.host | I am not lamenting the skin. I am lamenting how web is done overall.
It seems we are not expecting any heavy lifting on the web front are we?
Its not going to be an easy or cheap task either, to find a way towards a state of the art web documentation because that is something users are expecting. | 10:55:17 |
| fricklerhandwerk | In reply to @johannes.kirschbauer:scs.ems.host
I am not lamenting the skin. I am lamenting how web is done overall.
It seems we are not expecting any heavy lifting on the web front are we?
Its not going to be an easy or cheap task either, to find a way towards a state of the art web documentation because that is something users are expecting. Agreed, but let’s keep relative priorities in mind. I think a shiny surface (and that includes dynamic search) is one of the last of our problems. pennae‘s mention of regressions is important. Dropping in a different tool will break the hell out of existing links, and I agree that avoiding that has a chance of making things to take forever | 11:01:39 |
| infinisil | Splitting the manuals into multiple pages is also important. That can apparently be done without much work using nixos-render-docs though as pennae told me | 11:03:01 |
| @johannes.kirschbauer:scs.ems.host | So maybe we should start with those efforts.
I also have a plan how to avoid breaking existing links. | 11:05:42 |
| infinisil | A really stupid way to avoid breaking links without javascript would be to replace the contents of each section with a link to the new link :P | 11:06:37 |
| infinisil | Requires one click by users | 11:06:56 |
| @pennae:matrix.eno.space | In reply to @infinisil:matrix.org
Splitting the manuals into multiple pages is also important. That can apparently be done without much work using nixos-render-docs though as pennae told me yes, have a look out how option docs and release notes are rendered in the nixos manual. the facilities to split things have been there from day 1, and we've said this at least five times now | 11:16:00 |
| danielsidhion | As said, my biggest worry with splitting into multiple pages is that almost all current links won't work anymore. But IMO splitting into multiple pages will be a worse experience without at least a way to easily search those multiple pages | 11:31:51 |
