 | Nix Documentation | 421 Members |
| Discussion about documentation improvements around the Nix ecosystem | 87 Servers |
| Nix Documentation | 421 Members |
| Discussion about documentation improvements around the Nix ecosystem | 87 Servers |
| Sender | Message | Time |
|---|---|---|
| 8 Mar 2024 | ||
 @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 | 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.hostAgreed, 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 | In reply to @infinisil:matrix.orgyes, 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 |
| danielsidhion | I think the panic about regressions is somewhat overrated - it's not like we'd just drop some other tool without any sort of testing and without having both documentation methods side-by-side for at least some time to gather feedback | 11:33:13 |
| pennae | that is true, but redirections and search are so much easier to do as a retrofit than byt switching out your entire toolchain? | 11:33:18 |
| pennae | In reply to @danielsidhion:nixos.devagain, the problem is not the act of change but the sheer opportunity cost | 11:35:00 |
| pennae | a search index generator that emits a json file some existing search tool can read could be built in under an hour | 11:36:24 |
| danielsidhion | I appreciate any insights you have that would make search and redirection much easier, because the way I see, it would take quite some effort to write yet more custom code to make those work | 11:36:39 |
| pennae | it would not, because nrd already has the option to load javascript files and the nixos manual has demonstrated that such a global script can be used to redirect old links | 11:37:41 |
| pennae | * it would not, because nrd already has the option to load javascript files and the | 11:37:59 |
| pennae | and, to be perfectly clear, we have no objection to doing something cursed like rejiggering the nrd html exporter to build something mdbook could read for structure. but the exporter as exists now must also stay because pulling mdbook into the nixos manual build has since time immemorial been a Not Happening situation | 11:39:34 |
| danielsidhion | From my perspective, the overhead of maintaining custom tooling for everything is on the long run higher than the effort to migrate to a more well-known framework + custom plugins to solve specific needs. We have 0 nrd documentation and resources to let people get started, learn and extend it, and we require people who are familiar with a lot of concepts for them to start making any changes there. With a more well-known framework, we'd have lots more resources that many people without deeper technical knowledge would be able to help | 11:41:08 |
| pennae | as we said. consider the opportunity cost of a team already strapped for resources. | 11:43:37 |
| pennae | but it seems that this is a foregone conclusion, so. | 11:43:58 |
| danielsidhion | That's exactly what I'm considering when I look at the long term of both scenarios | 11:44:11 |
| danielsidhion | In any case, we don't even know yet how much work it would be to make any more well-known framework fit our needs - that's what I'm researching. If we find something that makes things easier in the long run, I'm definitely interested in putting the effort to migrate, but that's an if that we won't know until I finish looking at them | 11:45:21 |
| danielsidhion | I'm positive that it won't be hard to extend some well-known framework to our needs, but that could not be the case. I thought mdBook would be a good one and have been disappointed so far 🥲 there are a few other promising ones though | 11:46:40 |
| pennae | in that case, may there be great success for your research. | 11:47:42 |
| pennae left the room. | 11:47:53 | |
| fricklerhandwerk | Yes, to make it explicit: for the long term we have to weigh the cost of onboarding contributors to the infrastructure against the cost of adapting it to our evolving needs at given time. And costs on the contributors’ end are very hard to estimate, so usually all we’re left with is what we know about people who are currently there. That’s another issue with contributor churn: it’s very hard to even assess the trade-offs between evolving existing code and writing new code, because existing code can seem harder to grok than using a ready-made interface, and just as well can get trivial to grok with guidance. | 11:56:50 |
| fricklerhandwerk | * Yes, to make it explicit: for the long term we have to weigh the cost of onboarding contributors to the infrastructure against the cost of adapting it to our evolving needs at any given time. And costs on the contributors’ end are very hard to estimate, so usually all we’re left with is what we know about people who are currently there. That’s another issue with contributor churn: it’s very hard to even assess the trade-offs between evolving existing code and writing new code, because existing code can seem harder to grok than using a ready-made interface, and just as well can get trivial to grok with guidance. | 11:57:13 |
 raitobezarius | I just want to make a note that the new tech stack for the website has already created a staggering amount of regressions, I hope that the panic of regressions on the documentation stack will be unfounded. | 16:34:05 |