| 8 Mar 2024 |
 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 |
| 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:matrix.eno.space | 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:matrix.eno.space | In reply to @danielsidhion:nixos.dev
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 again, the problem is not the act of change but the sheer opportunity cost | 11:35:00 |
| @pennae:matrix.eno.space | 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 |
