| 14 Mar 2024 |
 @johannes.kirschbauer:scs.ems.host | In reply to @picnoir:alternativebit.fr
Hey, I just stumbled upon this:
At some point we agreed to move the manuals to nix.dev
https://github.com/NixOS/nixos-homepage/issues/1251#issuecomment-1994193106
Not sure what is the best place to discuss this. Obviously not the above issue :) So let's go with this matrix channel.
I'd like to voice some concern about that: there's a lot of hyperlinks pointing to the manual on the web. Doing so will break those for little benefit.
I think this matrix channel is always best for asking about documentation concerns. | 12:18:41 |
| @johannes.kirschbauer:scs.ems.host | Picnoir: can you give some more details:
there's a lot of hyperlinks pointing to the manual on the web
What exact links, do you mean on the nixos website or in nix.dev?
the manual on the web.
Do you mean all the manuals? Or the nixpkgs manual ? or the nixos manual ?
| 12:22:01 |
| @johannes.kirschbauer:scs.ems.host | * Picnoir: can you give some more details:
there's a lot of hyperlinks pointing to the manual on the web
What exact links, do you mean on the nixos website or in nix.dev?
the manual on the web.
Do you mean all the manuals? Or the nixpkgs manual ? or the nixos manual ?
| 12:22:58 |
 @picnoir:alternativebit.fr | I'm mostly talking about links living on blog posts and overall pages not controlled by the documentation team. | 12:23:03 |
| @picnoir:alternativebit.fr | * I'm mostly talking about links living on blog posts, wikis and overall pages not controlled by the documentation team. | 12:23:08 |
| @johannes.kirschbauer:scs.ems.host | * Picnoir: can you give some more details:
there's a lot of hyperlinks pointing to the manual on the web
What exact links, do you mean on the nixos website or in nix.dev?
the manual on the web.
Do you mean all the manuals? Or the nixpkgs manual ? or the nixos manual ?
| 12:23:27 |
| @picnoir:alternativebit.fr | And yes, all three main manuals: Nix, NixOS and Nixpkgs | 12:23:27 |
| @picnoir:alternativebit.fr | Nix for the language bit | 12:23:35 |
| @picnoir:alternativebit.fr | NixOS for the modules configurations. | 12:23:40 |
| @johannes.kirschbauer:scs.ems.host | Ah okay understood. | 12:23:54 |
| @picnoir:alternativebit.fr | Nixpkgs for the language-specific build systems. | 12:23:54 |
| @johannes.kirschbauer:scs.ems.host | Good concern. Implementing a simple redirection endpoint is quite hard. because most of the manuals are just one single page behind a single url.
Anchor tags #section-name are not sent to the server. This means it is essentially impossible to redirect from the old link to a new location.
Because from a server perspective
https://nixos.org/manual/nixpkgs/stable/#__placeA__
is exactly the same as
https://nixos.org/manual/nixpkgs/stable/#__placeB__
| 12:28:55 |
| @johannes.kirschbauer:scs.ems.host |
When a URL with an anchor tag is accessed, the browser uses the tag to scroll to a specific section of the page without making a server request for the anchor. The server only receives the part of the URL preceding the #.
| 12:30:37 |
| @johannes.kirschbauer:scs.ems.host | * When a URL with an anchor tag is accessed, the browser uses the tag to scroll to a specific section of the page without making a server request for the anchor. The server only receives the part of the URL preceding the #. | 12:30:43 |
| @johannes.kirschbauer:scs.ems.host | * Good concern. Implementing a simple redirection endpoint is quite hard/impossible. because most of the manuals are just one single page behind a single url.
Anchor tags #section-name are not sent to the server. This means it is essentially impossible to redirect from the old link to a new location.
Because from a server perspective
https://nixos.org/manual/nixpkgs/stable/#__placeA__
is exactly the same as
https://nixos.org/manual/nixpkgs/stable/#__placeB__
| 12:35:24 |
| @johannes.kirschbauer:scs.ems.host | This means migrating to any form of multipage documentation will always break the external links.
And there is unfortunately nothing we can do about it. ( At least not something i am aware of ) | 12:37:46 |
| @johannes.kirschbauer:scs.ems.host | In my opinion, the root of our current issues stems from the overuse of anchor tags. This overreliance has led to regressions and breakages that we're now struggling to address. The longer we delay taking action, the more severe and complex these problems become, exacerbating the situation further. | 12:40:11 |
| @picnoir:alternativebit.fr | What's the motivation behind migrating away from nixos.org? | 12:40:16 |
| @johannes.kirschbauer:scs.ems.host | nixos.org is just a domain. I saw the dicusssion that we could host the content of nix.dev on nixos.org.
Migration is mainly happening at the content level | 12:41:53 |
| @johannes.kirschbauer:scs.ems.host | afaik | 12:42:14 |
| @picnoir:alternativebit.fr | Right! | 12:44:28 |
| @picnoir:alternativebit.fr | I was talking about
At some point we agreed to move the manuals to nix.dev, yes. I don't have the source right now.
I still intend to make it happen one way or another. I started in October and didn't manage to finish yet because of conflicting priorities due to too many responsibilities.
https://github.com/NixOS/nixos-homepage/issues/1251#issuecomment-1994193106
| 12:44:50 |
| @picnoir:alternativebit.fr | I personally dislike the multi-page approach. The manuals structure is chaotic and require ctrl-f ing your way through it. Splitting it to multiple pages breaks this use case. | 12:46:43 |
| @picnoir:alternativebit.fr | That being said, I won't die on that hill. I did not spend a lot of time contributing to the manual lately, I don't want to be a blocker for people actually trying to improve the thing. Worst case scenario, we still can generate a single-page documentation and move it to a custom domain unoficially. | 12:48:33 |
| @picnoir:alternativebit.fr | * I personally dislike the multi-page approach. The current manuals structure is chaotic and require ctrl-f ing your way through it. Splitting it to multiple pages breaks this use case. | 12:48:59 |
| @picnoir:alternativebit.fr | * I personally dislike the multi-page approach. The current manuals structure is chaotic and require ctrl-f ing your way through it. Splitting it to multiple pages breaks this use case and makes information less easily available. | 12:50:30 |
| @johannes.kirschbauer:scs.ems.host | In reply to @picnoir:alternativebit.fr
I personally dislike the multi-page approach. The current manuals structure is chaotic and require ctrl-f ing your way through it. Splitting it to multiple pages breaks this use case and makes information less easily available. Ofc we must offer a search functionality. Otherwise nobody finds anything. ctrl-f wont work anymore ^^ | 12:57:55 |
| @johannes.kirschbauer:scs.ems.host | Our let me present you the current search mechanism: "ctrl-f"
I wonder why google doesnt have his index as a single html file that way you could just ctrl-f and dont have to enter it into the server.
Ah okay maybe thats a bit sarcastic now 😂 | 13:01:18 |
| @johannes.kirschbauer:scs.ems.host | * "Let me present you the current search mechanism: "ctrl-f"
I wonder why google doesnt have his index as a single html file that way you could just ctrl-f and dont have to enter it into the server."
Ah okay maybe thats a bit sarcastic now 😂 | 13:01:32 |
| @picnoir:alternativebit.fr left the room. | 13:10:36 |
