Move to docs.nixos.org

[infinisil]

There's currently two official domains for the Nix platform:

• nixos.org: Pretty much everything is under here. Main website, Hydra, cache, status page, search, reference documentation
• nix.dev: Tutorials and guides, since https://github.com/NixOS/nix.dev/pull/764 also the Nix reference manual

It's not great to have two domains because the default assumption is that different domains are different entities, so people don't expect both to be official.

My proposal to resolve this is by moving nix.dev to docs.nixos.org.

Since this only really involves the documentation team and is not that substantial of a change, we should be able to proceed with this plan by reaching consensus among the members, without the need for an RFC. Of course anybody is welcome to step in with arguments for/against this.

Related are:

• A fairly orthogonal RFC draft to move everything to nix.dev instead: https://github.com/nix-rfc-canonical-domain/rfcs/blob/canonical-domain/rfcs/1000-canonical-domain.md. See the issues for discussions, in particular:
  • https://github.com/nix-rfc-canonical-domain/rfcs/pull/1
  • https://github.com/nix-rfc-canonical-domain/rfcs/issues/10
  • https://github.com/nix-rfc-canonical-domain/rfcs/issues/8
• https://github.com/NixOS/foundation/issues/34
• https://github.com/NixOS/nix.dev/issues/290
• https://github.com/NixOS/foundation/issues/113#issuecomment-1906722707

Ping @NixOS/documentation-team, please indicate your opinion on this issue

[DanielSidhion]

I have no issues with this plan. Domain consistency feels more important to me. One thing to keep in mind is that the theme/css of nix.dev is different from the one usually used in nixos.org pages, so we may have to fix that at some point to maintain visual consistency as well. I don't think it's important to have that before the move to docs.nixos.org though, so I say go ahead!

[asymmetric]

How do you think the fact that the domain mentions NixOS affect the message that the docs are actually about the whole platform?

This is an old issue and not resolved by the nix.dev domain either, fwiw.

[infinisil]

How do you think the fact that the domain mentions NixOS affect the message that the docs are actually about the whole platform?

I believe that's mainly an orthogonal issue, it's not really affected by this. I guess if we do decide to use nix.dev in the end, we'd be moving back-and-forth nix.dev -> docs.nixos.org -> docs.nix.dev, which is a bit special, but not a problem.

[fricklerhandwerk]

I'm struggling to make up my mind about this. So I'm not enthusiastic, but it's probably not wrong, and therefore I won't oppose.

Given this is quite an impactful change nonetheless, and the discussion is scattered over a good number of threads, I'd really appreciate a summary of the trade-offs for posterity though. Sorry if that sounds like "please make an RFC" (I really don't want more RFCs). But not having a summary for the announcement will very likely lead to questions and raised concerns, and more scattered discussion. If not communicated properly, most outsiders will see this and think "what the hell are they doing there".

Assuming no one from the docs team opposes, how about making a Discourse post with all we had so far, and if no one cries up, go ahead and implement it? We may as well go on and rename this repository to NixOS/docs for consistency.

[infinisil]

I really think the basic idea of RFCs is great: Writing down motivation, detailed design, arguments and alternatives for a decision (also see ADR). It would be unfortunate if the negative stigma of the RFC process discourages us from writing such documents.

So this sounds like a great plan to me, I'll try to write this down in such a format here once I have some time to spare!

[infinisil]

@GetPsyched started with an effort to write an RFC in this repository. I think it's better to keep this separate from https://github.com/nix-rfc-canonical-domain/rfcs, since that one is more about moving to another domain.

Just opened a PR to add some stuff: https://github.com/GetPsyched/nixos-domain-unification/pull/1

[GetPsyched]

I think the only blocker right now is the unresolved question of there being docs for NixOS itself; however, that could be the new official wiki, likely located at wiki.nixos.org.

I don't mean to add unnecessary additional discussion on the topic, but consider these alternatives:

• Move the existing nixos.org/learn to docs.nixos.org and we can go deeper from there, docs.nixos.org/nixos, docs.nixos.org/nix.
• Same as above but on learn.nixos.org

[roberth]

So nix.dev will become a landing page for the Nix project then?

[GetPsyched]

So nix.dev will become a landing page for the Nix project then?

The original proposal was to move nix.dev to docs.nixos.org, and then nixos.org to nix.dev. This has shifted to nix.dev moving to docs.nixos.org, and that's it.

Feel free to read more in the original comment of this issue or the "RFC" in my repo for reference.

[NobbZ]

To me this feels as if we are yet again mixing up the products and mangling it into one…

We should strive to a clear seperation of concerns and do a strict distinction between nix the build tool + nixpkgs as kind of its stdlib on one side and NixOS as the Linux distribution built using nix on the other side.

If I were to visit docs.nixos.org I'd expect to see what is currently available under nixos.org/manuals/nixos, not some mostly nix related cookbook.

If we were to collect everything under nixos.org, I'd prefer nix.nixos.org/docs or something like that much more, to make clear, this is about nix specifically!

[fricklerhandwerk]

@NobbZ that's also generally my concern, but between docs.nixos.org/nix and nix.nixos.org/docs is only a cosmetic difference. What we're building here is an entry point to the ecosystem's documentation. That needs a place. Today it only may appear like a Nix-specific cookbook because we haven't systematically dealt with NixOS yet.

There's still an option to move everything somewhere else (such as nix.dev that we currently own or nix.org if we ever get it) and rightfully make NixOS a special case in its own corner. But that's future work.

[hugosenari]

@infinisil

nix.land

I liked it, I try to buy it, but the price was so high. To be honest, would not use it for nix home page, I'm biased since I want it for nixos.land.

Related: :spider_web: Nix related domains that ~~I~~ someone here controls Pre-RFC: A single canonical domain name (forum)

BTW, nixify.io is available.