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.

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.

In reply to @raitobezarius:matrix.org
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.

In reply to @stablejoy:matrix.org
How can one integrate more of the manuals and documentation directly with Nix? Like if Nix could handle a greater share of the workload, maintaining the website might become simpler. Meaning if it can package anything can it package a website manual in a way?

It is in principle possible to write a static site generator in the Nix language, if that's what you mean. It has been done at least once. Whether that will make anything simpler to maintain is a matter of implementation quality and maturity of language tooling.

The practical question is always "who's gonna do it". And as @pennae said, we already have something that works. Someone just has to dig into it and make things happen.

In reply to @stablejoy:matrix.org
How can one integrate more of the manuals and documentation directly with Nix? Like if Nix could handle a greater share of the workload, maintaining the website might become simpler. Meaning if it can package anything can it package a website manual in a way?

https://cs.tvl.fyi/depot/-/blob/users/sterni/nix/html/README.md
You mean something like this?

A dsl (by sterni for directly rendering html from nix code, of course this has major performance issues and i you'd be crazy to use it productively but its certainly an interesting experiement.

In reply to @johannes.kirschbauer:scs.ems.host

https://cs.tvl.fyi/depot/-/blob/users/sterni/nix/html/README.md
You mean something like this?

A dsl (by sterni for directly rendering html from nix code, of course this has major performance issues and i you'd be crazy to use it productively but its certainly an interesting experiement.

In reply to @fricklerhandwerk:matrix.org
Also this: https://github.com/static-nix/styx

In reply to @fricklerhandwerk:matrix.org
Also this: https://github.com/static-nix/styx

It even renders its own documentation: https://styx-static.github.io/styx-site/documentation/

I'd still recommend against it, because it follows the same paradigm as any other static site generator. You won't gain much.

In reply to @johannes.kirschbauer:scs.ems.host
This styx thing looks like a differently styled version of our huge single page manual.
My mouse catched fire from scrolling around inside of it^^

In reply to @fricklerhandwerk:matrix.org
🙄 Yeah that's merely about some parameter juggling. Apart from that, there always should be single-page rendering, and that's just as much of a valid way for reading documents. I think it's a regression that the Nix manual did not keep the single page as an alternative. The dynamic search sucks, and you effectively need an entire web browser for it to work.